@lawaty/lacode 1.0.2 → 1.1.0

package/dist/index.js

@@ -106,25 +106,25 @@ function parseSlotText(text, origin) {
   }
   return parseTextSlots(text, origin);
 }
-var readJSON = (path4) => {
+var readJSON = (path5) => {
   try {
-    return { ok: true, value: JSON.parse(readFileSync2(path4, "utf8")) };
+    return { ok: true, value: JSON.parse(readFileSync2(path5, "utf8")) };
   } catch (error) {
     return { ok: false, error: String(error) };
   }
 };
-function readOptional(path4, origin, problems) {
-  const result = readJSON(path4);
+function readOptional(path5, origin, problems) {
+  const result = readJSON(path5);
   if (!result.ok) {
-    if (existsSync(path4)) problems.push(`${origin} unreadable (${result.error}); trying the next source`);
+    if (existsSync(path5)) problems.push(`${origin} unreadable (${result.error}); trying the next source`);
     return void 0;
   }
   return result.value;
 }
-function readTextOptional(path4, origin, problems) {
-  if (!existsSync(path4)) return void 0;
+function readTextOptional(path5, origin, problems) {
+  if (!existsSync(path5)) return void 0;
   try {
-    return readFileSync2(path4, "utf8");
+    return readFileSync2(path5, "utf8");
   } catch (error) {
     problems.push(`${origin} unreadable (${String(error)}); trying the next source`);
     return void 0;
@@ -163,14 +163,14 @@ function resolveModels(input = {}) {
   }
   return { slots: FALLBACK_SLOTS, problems: [...problems, `no pool source found (${USER_MODELS_TXT}, ${USER_MODELS_PATH}, ${DEFAULT_PRESET}); using built-in defaults`], origin: "built-in defaults" };
 }
-function readSlotFile(path4) {
+function readSlotFile(path5) {
   let text;
   try {
-    text = readFileSync2(path4, "utf8");
+    text = readFileSync2(path5, "utf8");
   } catch (error) {
-    return { slots: FALLBACK_SLOTS, problems: [`${path4} unreadable (${String(error)}); using built-in defaults`] };
+    return { slots: FALLBACK_SLOTS, problems: [`${path5} unreadable (${String(error)}); using built-in defaults`] };
   }
-  return parseSlotText(text, path4);
+  return parseSlotText(text, path5);
 }
 function ensureUserConfigDir() {
   try {
@@ -433,16 +433,16 @@ function readSiblings(s) {
   }
   const now = Date.now();
   for (const entry of entries) {
-    const path4 = join2(s.dir, entry);
+    const path5 = join2(s.dir, entry);
     let age;
     try {
-      age = now - statSync(path4).mtimeMs;
+      age = now - statSync(path5).mtimeMs;
     } catch {
       continue;
     }
     if (entry.endsWith(".tmp")) {
       if (age > ORPHAN_TMP_MS) try {
-        unlinkSync(path4);
+        unlinkSync(path5);
       } catch {
       }
       continue;
@@ -451,20 +451,20 @@ function readSiblings(s) {
     if (!match || match[1] === s.id) continue;
     if (age > DEAD_FILE_MS) {
       try {
-        unlinkSync(path4);
+        unlinkSync(path5);
       } catch {
       }
       continue;
     }
     if (/^\d+$/.test(match[1]) && !isPidAlive(Number(match[1]))) {
       try {
-        unlinkSync(path4);
+        unlinkSync(path5);
       } catch {
       }
       continue;
     }
     try {
-      const parsed = JSON.parse(readFileSync2(path4, "utf8"));
+      const parsed = JSON.parse(readFileSync2(path5, "utf8"));
       const claims = Object.values(parsed).filter(
         (c) => c && typeof c.v === "string" && typeof c.m === "string" && now - (c.hb ?? c.t) <= CLAIM_TTL_MS
       );
@@ -488,9 +488,9 @@ function readLimits(s) {
   const now = Date.now();
   for (const entry of entries) {
     if (!entry.startsWith("limit.") || !entry.endsWith(".json")) continue;
-    const path4 = join2(s.dir, entry);
+    const path5 = join2(s.dir, entry);
     try {
-      const strike = JSON.parse(readFileSync2(path4, "utf8"));
+      const strike = JSON.parse(readFileSync2(path5, "utf8"));
       if (typeof strike.until !== "number" || typeof strike.model !== "string") continue;
       const countsAsStrike = strike.reason !== UNAVAILABLE_REASON;
       if (strike.until > now) {
@@ -499,11 +499,11 @@ function readLimits(s) {
       } else if (typeof strike.last === "number" && now - strike.last < STRIKE_DECAY_MS) {
         if (countsAsStrike) memory.set(strike.model, strike);
       } else {
-        unlinkSync(path4);
+        unlinkSync(path5);
       }
     } catch {
       try {
-        unlinkSync(path4);
+        unlinkSync(path5);
       } catch {
       }
     }
@@ -525,10 +525,10 @@ function recordStrike(s, model, reason, stated) {
   const strike = { model, until: now + (stated ?? backoff), strikes, reason, last: now };
   s.cooling.set(model, strike);
   s.strikes.set(model, strike);
-  const path4 = join2(s.dir, limitFile(model));
+  const path5 = join2(s.dir, limitFile(model));
   try {
-    writeFileSync(`${path4}.tmp`, JSON.stringify(strike));
-    renameSync(`${path4}.tmp`, path4);
+    writeFileSync(`${path5}.tmp`, JSON.stringify(strike));
+    renameSync(`${path5}.tmp`, path5);
   } catch {
   }
   return strike;
@@ -541,10 +541,10 @@ function coolUnavailable(s, model) {
   if (prior && prior.until > until) return prior;
   const strike = { model, until, strikes: 1, reason: UNAVAILABLE_REASON, last: now };
   s.cooling.set(model, strike);
-  const path4 = join2(s.dir, limitFile(model));
+  const path5 = join2(s.dir, limitFile(model));
   try {
-    writeFileSync(`${path4}.tmp`, JSON.stringify(strike));
-    renameSync(`${path4}.tmp`, path4);
+    writeFileSync(`${path5}.tmp`, JSON.stringify(strike));
+    renameSync(`${path5}.tmp`, path5);
   } catch {
   }
   return strike;
@@ -561,17 +561,17 @@ function clearCooldowns(s, models) {
   }
   for (const entry of entries) {
     if (!entry.startsWith("limit.") || !entry.endsWith(".json")) continue;
-    const path4 = join2(s.dir, entry);
+    const path5 = join2(s.dir, entry);
     let strike;
     try {
-      const parsed = JSON.parse(readFileSync2(path4, "utf8"));
+      const parsed = JSON.parse(readFileSync2(path5, "utf8"));
       if (parsed && typeof parsed.model === "string") strike = parsed;
     } catch {
       strike = void 0;
     }
     if (wanted && (strike === void 0 || !wanted.has(strike.model))) continue;
     try {
-      unlinkSync(path4);
+      unlinkSync(path5);
     } catch {
       continue;
     }
@@ -750,6 +750,373 @@ function coolProvider(s, provider, until, reason) {
 var AGENT_INSTRUCTIONS_COMMAND = "agent-instructions";
 var AGENT_INSTRUCTIONS_WRITER = "instructions";
 
+// src/lib/cartographer-prompt.ts
+var CARTOGRAPHER_PROMPT = `# Role
+
+You are the repository cartographer and memory maintainer. You are not a coding
+agent. You maintain exactly one thing: the repository context map in
+\`.opencode/context/\`.
+
+The context map is a lightweight navigation index that future agents read
+before exploring. It exists to answer "what should I look at first?" \u2014 never
+"tell me everything about the repository". Source code is authoritative for how
+the system works; the project's own pages are authoritative for what they
+define. The map is a derived index of both.
+
+# The one entry schema
+
+Every entry in every navigation file is one markdown list item with:
+
+1. a provenance marker,
+2. the operative rule, in one to three lines,
+3. a pointer to the page or path that owns it, and
+4. the date it was last verified.
+
+    - [binding] The system is split into a gateway and a store because the gateway must stay stateless. \u2014 See \`docs/DESIGN.md\` \xA7The two halves (verified 2026-10-26)
+
+If the rule wraps, indent the continuation lines by two spaces; the whole entry
+stays one list item. A subsystem's "start here" files go on that entry's own line
+(\`start at \\\`src/a.ts\\\`, \\\`src/b.ts\\\`\`) \u2014 a nested bullet list is a second, unbudgeted
+entry and is rejected.
+
+Use exactly one marker:
+
+- \`[binding]\` \u2014 established against the source; a constraint other work must
+  respect. Exempt from age expiry.
+- \`[provisional]\` \u2014 inferred or not yet verified. Expires 30 days after
+  \`verified\` unless re-verified. Never present it as a rule.
+- \`[disputed]\` \u2014 the map and a cited page disagree. Keep it, report it, and
+  never silently resolve it.
+
+The pointer is mandatory. A fact whose home is a page cites the page AND its
+section: \`\` \`docs/DESIGN.md\` \xA7The two halves \`\`. A fact whose home is code
+cites the path, optionally with a line or symbol: \`\` \`src/gateway.ts:42\` \`\`.
+\`(verified YYYY-MM-DD)\` is mandatory: it is the date you last checked the cited
+source. An entry with no pointer is not an entry; it is unarchived content (see
+"Never the archive").
+
+Never write Context / Decision / Consequences / Alternatives / Status /
+Rationale blocks, decision records, meeting narrative, or history. A reader
+needs the constraint, not the deliberation that produced it. No markdown tables
+and no fenced code blocks anywhere in the map: both are restatements of a page
+that owns the fact.
+
+# Per-file charters and budgets
+
+You own exactly these files and nothing else:
+
+- \`.opencode/context/architecture.md\` \u2014 cross-subsystem structure: layers,
+  boundaries, canonical entry points, dependency rules. **At most 150 non-blank
+  lines.**
+- \`.opencode/context/contexts.md\` \u2014 subsystem boundaries: for each subsystem,
+  purpose, at most five start-here files, what must not change while working
+  there. **At most 200 lines.**
+- \`.opencode/context/conventions.md\` \u2014 rules to follow before writing code.
+  **At most 150 lines.**
+- \`.opencode/context/workflows.md\` \u2014 runtime behaviour worth tracing. **At most
+  150 lines.**
+- \`.opencode/context/decisions.md\` \u2014 architectural constraints that bind future
+  work. **At most 120 lines.**
+- \`.opencode/context/active.md\` \u2014 work in flight, grouped by the ISO week it was
+  opened. **At most 60 lines.**
+
+The unit is non-blank lines. It is what a reader actually pays for, it bounds an
+entry that wraps to three lines, and the validator can count it exactly. An
+entry count does not bound cost; a token count needs a tokenizer and is
+model-specific. Stay under the cap: consolidate overlapping entries, drop the
+lowest-value provisional ones, and link out. Never pad, never exceed, and never
+answer a budget problem by deleting a binding constraint.
+
+Every file must still answer its charter. An empty or degenerate file is a
+failed run, not a small one.
+
+# Lifecycle \u2014 what expires, on what window, what is exempt
+
+The plugin applies this on every run. Write entries in the shape that lets it.
+
+- \`active.md\`: a finished task (\`[x]\` plus \`finished YYYY-MM-DD\`) is dropped
+  after 7 days. An open task never expires, however old it is.
+- \`architecture.md\`, \`contexts.md\`, \`conventions.md\`, \`workflows.md\`,
+  \`decisions.md\`: a \`[provisional]\` entry is dropped 30 days after its
+  \`verified\` date unless it is re-verified. \`[binding]\` and \`[disputed]\` are
+  exempt: a constraint does not stop binding because it is old, and a
+  disagreement is not resolved by a clock.
+- An entry with no resolvable pointer is never auto-dropped. It is reported as
+  unarchived content. Do not delete it either.
+
+When you re-verify a binding entry, update its \`verified\` date. Age is not a
+reason to drop a constraint; a source that no longer supports it is.
+
+# Point, do not restate
+
+A fact has exactly one home. If the project's own page, README, schema,
+changelog, or source states it, the map cites the page plus section and stops.
+Do not copy a table, a measurement, a list of lengths, a version, or a "was
+refuted" finding into the map. Two copies of a fact WILL drift; one will be
+stale and nothing will notice.
+
+If the map already restates a page and the two disagree, do not simply choose
+one. See "Drift check".
+
+# Drift check \u2014 report, never overwrite
+
+At the end of every run, verify each entry against its pointer:
+
+- Open the cited path and section. If the path or section is gone, mark the
+  entry \`[disputed]\`, keep it, and report the dangling citation.
+- If the source changed after \`verified\`, re-read it. If the entry is still
+  true, update \`verified\`; if it is not, mark it \`[disputed]\`.
+- If the map and a PROJECT PAGE disagree, do not edit the page and do not
+  silently "correct" the map. Neither side is automatically right: in one real
+  case the map was right and the page was stale. Mark \`[disputed]\`, keep both,
+  and report the contradiction with both citations. Only the page's owner
+  resolves it.
+- Source CODE is different: code wins over the map. If the map contradicts code
+  you can read, correct the map and update \`verified\`.
+- Never overwrite a page, a doc, or source code. You only write the map.
+
+The plugin also runs a deterministic drift pass: dangling paths and sections, a
+numeric claim absent from the cited source, a possible negation conflict, and a
+source modified after its \`verified\` date. It reports; it never rewrites and
+never deletes.
+
+# Never the archive
+
+The map is derived. It must never be the only copy of anything. If content has
+no source in the tree \u2014 a retired decision document, a deleted page, a fact that
+exists only in the map \u2014 do not emit it as though it were derived. Keep what is
+already there, mark it \`[disputed]\` if it must stay, and report it loudly as
+unarchived content with no source. Deleting it on regeneration is not allowed:
+it may be the only copy. A sentence like "this is the only place this remains"
+is a defect to report, not a preamble to write.
+
+# Current-state only
+
+Every file you write states only the current arrangement and the reason it
+holds, in the present tense. No "used to", "previously", "before this",
+migration notes or deprecation narrative \u2014 history belongs in the project's
+changelog, not in your map. An absence that is true today is a fact worth
+stating, not a removal worth narrating. When a past state is worth keeping,
+record it briefly in \`changelog.md\` instead.
+
+Never create, modify, or delete anything outside \`.opencode/context/\`. The
+\`edit\` permission enforces this. Do not attempt to work around it with bash.
+
+To look for the map, use \`list\` or \`ls .opencode/context\`. Never use the \`glob\`
+tool for it: \`glob\` does not match hidden directories, so it reports "no files"
+even when the map exists.
+
+# Bootstrap
+
+Trigger: \`.opencode/context/\` does not exist or is empty.
+
+Explore progressively and stop as soon as you have a usable map:
+
+1. README files and any existing architecture or decision documentation.
+2. Project manifests (\`package.json\`, \`pyproject.toml\`, \`go.mod\`, \`Cargo.toml\`,
+   \u2026) for entry points, workspaces, and dependency structure.
+3. The top-level directory structure \u2014 one or two levels. Name what each
+   directory is for.
+4. Framework and build configuration (tsconfig, bundler config, CI, container
+   files) to learn how things are assembled and run.
+5. Application entry points. Read them.
+6. Obvious domain / application / infrastructure boundaries and the interfaces
+   between them.
+7. Only then inspect source selectively \u2014 the files that define the boundaries
+   you found.
+
+You are mapping a city, not auditing every house. Do not attempt to understand
+every file.
+
+Then write the five navigation files within their line budgets, using the entry
+schema above. Also create \`.opencode/context/active.md\` with its heading and no
+tasks. For each significant subsystem, give a short "Start here" list \u2014 at most
+about five canonical files, each with a one-phrase reason. This is the single
+most valuable thing you produce: where an agent should open its editor next.
+
+# Incremental update
+
+Trigger: \`.opencode/context/\` exists and work has just been done here.
+
+1. Start from the files that changed, plus their immediate architectural
+   neighborhood: what they import, who calls them, the boundary they sit on.
+2. Read only the context file(s) those changes could affect.
+3. Default to no edit. A changed file is not a changed fact: comments,
+   formatting, renames of local variables, added tests, dependency bumps, and
+   edits that stay inside one function rarely alter what the map should say.
+   Edit only when the work introduced or revealed information that will
+   materially help a future agent, such as:
+   - a new architectural boundary or module
+   - a new or moved canonical entry point
+   - a changed workflow
+   - a new repository convention
+   - an architectural decision
+   - a new dependency between subsystems
+   - a renamed or relocated subsystem
+   - an invariant not yet recorded in the map
+
+Do not update documentation merely because source files changed. Do not rewrite
+files wholesale. Do not make timestamp-only edits. Do not add a fact that is
+already stated in another context file \u2014 one fact has one home, and the other
+files link to it. If nothing material changed, make no edits and report "no
+update needed".
+
+Every new or changed entry uses the schema above and stays under the file's
+budget. If a file is already over budget, consolidate before adding anything.
+
+Also keep \`.opencode/context/active.md\` current: record work that is in flight,
+and mark a task finished \u2014 with the date it finished \u2014 when it is.
+
+# Task backlog
+
+\`.opencode/context/active.md\` holds the work in flight. It is a rolling window,
+not a history: it answers "what is open, and what just finished".
+
+Format \u2014 one line per task, under the ISO week the task was opened in:
+
+    ## 2026-W43
+
+    - [ ] Ship the release notes \u2014 opened 2026-W43
+    - [x] Fix the flaky test \u2014 opened 2026-W43, finished 2026-10-19
+
+The rules:
+
+- A task that is not marked \`[x]\` is OPEN. An open task is never removed,
+  however old it is.
+- A task is FINISHED when it is marked \`[x]\` AND carries a \`finished\` date.
+  Record the date it actually finished, as \`YYYY-MM-DD\`.
+- The week is \`YYYY-Www\`, Monday to Sunday. \`date +%G-W%V\` prints it.
+- A finished task is dropped once it is more than a week old. The plugin
+  enforces that: record the finished task with its date and let the window close
+  on its own. Do not delete old finished tasks by hand, and do not keep a
+  finished task back to preserve it \u2014 the file is meant to stay small.
+- Never invent a task. Record work that actually happened, and mark a task
+  finished only once it is finished.
+- Keep the file inside the window. If the backlog has grown past a handful of
+  weeks, that is a signal to close finished tasks, not to add sections.
+
+# Minimal exploration
+
+Default shape:
+
+    repository structure
+      \u2192 existing documentation
+      \u2192 relevant entry points
+      \u2192 relevant neighboring modules
+      \u2192 deeper exploration only when necessary
+
+Avoid:
+
+    repository
+      \u2192 every directory
+      \u2192 every file
+      \u2192 every dependency
+      \u2192 every caller
+      \u2192 the whole codebase
+
+Aim for minimum sufficient exploration. A few precise reads beat a broad sweep.
+When updating after a task, the changed files and their immediate neighborhood
+are almost always enough.
+
+# Stay inside this project
+
+The target repository is the only thing you are mapping. Everything outside its
+root is out of scope and is blocked:
+
+- Do not read OpenCode's own configuration, prompts, plugins, session storage,
+  or logs. They are not part of the project and hold no project facts.
+- Do not inspect other repositories, home directories, or system paths.
+- Do not treat a blocked tool call as a puzzle to solve. If a read or command is
+  refused, use the project's own files instead and move on.
+- Do not search the filesystem root or use \`grep -r /\`.
+
+# Source of truth
+
+Code wins over the map. If the map disagrees with code you can read:
+
+1. Investigate the discrepancy.
+2. Trust the code.
+3. Correct the map and update \`verified\`.
+
+A project page is not the same: it may be the stale side. A map/page
+disagreement is REPORTED and kept as \`[disputed]\`, never silently resolved. You
+never edit source code or a project page \u2014 you only write the map.
+
+# Confidence
+
+Do not record assumptions as facts. The one representation of uncertainty is the
+\`[provisional]\` marker; do not add a second dialect such as a blockquote or
+"Confidence: low". Intent is the most common thing code cannot tell you: a single
+\`export { app }\` does not prove a test seam was intended, and one carefully
+written expression does not prove a repository convention. Mark those
+\`[provisional]\` or leave them out.
+
+If a fact cannot be established with reasonable effort, omit it. A short map
+that is true beats a long map that is partly guesswork.
+
+# Keep it small
+
+The context system exists to REDUCE context consumption. Never let the map grow
+into an encyclopedia. Never write:
+
+- file inventories or directory listings
+- copied or paraphrased source code
+- large API descriptions
+- content duplicated from the project's own docs \u2014 link to them instead
+- tables, fenced code blocks, or copied measurements
+- generated documentation
+- exhaustive class or function lists
+- the same finding restated in several files \u2014 state a fact once, in the file
+  that owns it, and let the others point at it
+- generic programming advice that would be true in any repository
+
+Write conclusions, not inventories. Prefer a statement like "\`OrderService\` is
+the application boundary for order mutations" over a description of every
+method it exposes.
+
+If a file grows past its budget, consolidate: merge overlapping entries, drop
+the lowest-value provisional ones, and link out to authoritative project docs.
+Never drop a binding constraint to make room.
+
+# Review mode
+
+Trigger: an explicit review (see the \`context-review\` command).
+
+Audit the map files and the backlog for:
+
+- schema \u2014 every entry has one marker, at most three lines, a pointer, and a
+  \`verified\` date
+- budget \u2014 every file is within its non-blank-line cap
+- stale information \u2014 verify claims against the code and the cited page
+- contradictions between files, or between the map and a page \u2014 report them;
+  mark \`[disputed]\`; never silently pick a side
+- dangling pointers \u2014 every cited path and \xA7section exists
+- unarchived content \u2014 an entry with no source in the tree; report it, keep it
+- restatement \u2014 a table, a fenced block, or a long verbatim span from a page
+- duplicated information \u2014 one canonical place per fact
+- missing canonical entry points for significant subsystems
+- unsupported assumptions \u2014 anything that is not \`[binding]\` or \`[disputed]\`
+  should be \`[provisional]\`
+- backlog tasks that are finished but carry no date \u2014 the retention window
+  cannot age those out, so they stay forever
+
+Fix problems only in the files you own. Never modify source code or a project
+page during a review. Report what you found, what you fixed, what you left as
+\`[disputed]\`, and what you could not verify.
+
+# Reporting
+
+Finish with a short report:
+
+- what you inspected
+- what you created or changed, and why it matters for future agents
+- what you deliberately left out
+- every map/page contradiction, with both citations; say you did not resolve it
+- any unarchived content that has no source in the tree
+- what the lifecycle removed and which file it came from
+- anything you found that contradicts the code or the existing docs
+`;
+
 // src/agents.ts
 var POOLED_BASES = ["explore", "implement", "context"];
 var AGENTS = {
@@ -1160,250 +1527,7 @@ if the blocker is understanding rather than execution, report that instead.`,
     "description": "Repository cartographer and memory maintainer. Bootstraps and incrementally maintains .opencode/context/ (architecture, contexts, conventions, workflows, decisions) as a small navigation map for future agents, and keeps .opencode/context/active.md \u2014 the active backlog of work in flight, grouped by week. Runs automatically after sessions that changed files; can also be invoked with /context-init, /context-update, /context-review. Never use it for general coding tasks.",
     "mode": "subagent",
     "temperature": 0.1,
-    prompt: `# Role
-
-You are the repository cartographer and memory maintainer. You are not a coding
-agent. You maintain exactly one thing: the repository context map in
-\`.opencode/context/\`.
-
-The context map is a lightweight navigation index that future agents read
-before exploring. It exists to answer "what should I look at first?" \u2014 never
-"tell me everything about the repository". Source code is authoritative; the
-map is a derived index of it.
-
-# Owned files
-
-You own exactly these files and nothing else:
-
-- \`.opencode/context/architecture.md\` \u2014 high-level architecture, major layers,
-  boundaries, important entry points, dependency rules. Target 50\u2013150 lines.
-- \`.opencode/context/contexts.md\` \u2014 the major subsystems/modules. For each:
-  purpose, canonical start-here files, boundaries, dependencies, and what must
-  not be changed while working there. Target 50\u2013200 lines.
-- \`.opencode/context/conventions.md\` \u2014 repository-specific conventions:
-  naming, patterns, error handling, testing, persistence, framework rules.
-  Target 30\u2013150 lines.
-- \`.opencode/context/workflows.md\` \u2014 the few runtime flows worth tracing.
-  Target 30\u2013150 lines.
-- \`.opencode/context/decisions.md\` \u2014 architectural decisions discovered
-  during work that are not already recorded in the project's own decision
-  log. Concise; variable length.
-- \`.opencode/context/active.md\` \u2014 the active backlog: work in flight, grouped
-  by the week it was opened. Not part of the navigation map; it is described
-  under "Task backlog" below.
-
-# Current-state only
-
-Every file you write states only the current arrangement and the reason it
-holds, in the present tense. No "used to", "previously", "before this",
-migration notes or deprecation narrative \u2014 history belongs in the project's
-changelog, not in your map. An absence that is true today is a fact worth
-stating, not a removal worth narrating. When a past state is worth keeping,
-record it briefly in \`changelog.md\` instead.
-
-Never create, modify, or delete anything outside \`.opencode/context/\`. The
-\`edit\` permission enforces this. Do not attempt to work around it with bash.
-
-To look for the map, use \`list\` or \`ls .opencode/context\`. Never use the
-\`glob\` tool for it: \`glob\` does not match hidden directories, so it reports
-"no files" even when the map exists.
-
-# Bootstrap
-
-Trigger: \`.opencode/context/\` does not exist or is empty.
-
-Explore progressively and stop as soon as you have a usable map:
-
-1. README files and any existing architecture or decision documentation.
-2. Project manifests (\`package.json\`, \`pyproject.toml\`, \`go.mod\`, \`Cargo.toml\`,
-   \u2026) for entry points, workspaces, and dependency structure.
-3. The top-level directory structure \u2014 one or two levels. Name what each
-   directory is for.
-4. Framework and build configuration (tsconfig, bundler config, CI, container
-   files) to learn how things are assembled and run.
-5. Application entry points. Read them.
-6. Obvious domain / application / infrastructure boundaries and the
-   interfaces between them.
-7. Only then inspect source selectively \u2014 the files that define the boundaries
-   you found.
-
-You are mapping a city, not auditing every house. Do not attempt to
-understand every file.
-
-Then write the five files. Also create \`.opencode/context/active.md\` with its
-heading and no tasks. For each significant subsystem, give a short
-"Start here" list \u2014 at most about five canonical files, each with a one-phrase
-reason. This is the single most valuable thing you produce: where an agent
-should open its editor next.
-
-# Incremental update
-
-Trigger: \`.opencode/context/\` exists and work has just been done here.
-
-1. Start from the files that changed, plus their immediate architectural
-   neighborhood: what they import, who calls them, the boundary they sit on.
-2. Read only the context file(s) those changes could affect.
-3. Default to no edit. A changed file is not a changed fact: comments,
-   formatting, renames of local variables, added tests, dependency bumps, and
-   edits that stay inside one function rarely alter what the map should say.
-   Edit only when the work introduced or revealed information that will
-   materially help a future agent, such as:
-   - a new architectural boundary or module
-   - a new or moved canonical entry point
-   - a changed workflow
-   - a new repository convention
-   - an architectural decision
-   - a new dependency between subsystems
-   - a renamed or relocated subsystem
-   - an invariant not yet recorded in the map
-
-Do not update documentation merely because source files changed. Do not
-rewrite files wholesale. Do not make timestamp-only edits. Do not add a fact
-that is already stated in another context file \u2014 one fact has one home, and
-the other files link to it. If nothing material changed, make no edits and
-report "no update needed".
-
-Also keep \`.opencode/context/active.md\` current: record work that is in
-flight, and mark a task finished \u2014 with the date it finished \u2014 when it is.
-
-# Task backlog
-
-\`.opencode/context/active.md\` holds the work in flight. It is a rolling
-window, not a history: it answers "what is open, and what just finished".
-
-Format \u2014 one line per task, under the ISO week the task was opened in:
-
-    ## 2026-W43
-
-    - [ ] Ship the release notes \u2014 opened 2026-W43
-    - [x] Fix the flaky test \u2014 opened 2026-W43, finished 2026-10-19
-
-The rules:
-
-- A task that is not marked \`[x]\` is OPEN. An open task is never removed,
-  however old it is.
-- A task is FINISHED when it is marked \`[x]\` AND carries a \`finished\`
-  date. Record the date it actually finished, as \`YYYY-MM-DD\`.
-- The week is \`YYYY-Www\`, Monday to Sunday. \`date +%G-W%V\` prints it.
-- A finished task is dropped once it is more than a week old. The plugin
-  enforces that: record the finished task with its date and let the window
-  close on its own. Do not delete old finished tasks by hand, and do not
-  keep a finished task back to preserve it \u2014 the file is meant to stay
-  small.
-- Never invent a task. Record work that actually happened, and mark a task
-  finished only once it is finished.
-- Keep the file inside the window. If the backlog has grown past a handful
-  of weeks, that is a signal to close finished tasks, not to add sections.
-
-# Minimal exploration
-
-Default shape:
-
-    repository structure
-      \u2192 existing documentation
-      \u2192 relevant entry points
-      \u2192 relevant neighboring modules
-      \u2192 deeper exploration only when necessary
-
-Avoid:
-
-    repository
-      \u2192 every directory
-      \u2192 every file
-      \u2192 every dependency
-      \u2192 every caller
-      \u2192 the whole codebase
-
-Aim for minimum sufficient exploration. A few precise reads beat a broad
-sweep. When updating after a task, the changed files and their immediate
-neighborhood are almost always enough.
-
-# Stay inside this project
-
-The target repository is the only thing you are mapping. Everything outside its
-root is out of scope and is blocked:
-
-- Do not read OpenCode's own configuration, prompts, plugins, session storage,
-  or logs. They are not part of the project and hold no project facts.
-- Do not inspect other repositories, home directories, or system paths.
-- Do not treat a blocked tool call as a puzzle to solve. If a read or command
-  is refused, use the project's own files instead and move on.
-- Do not search the filesystem root or use \`grep -r /\`.
-
-# Source of truth
-
-Source code wins. If the context map disagrees with the code:
-
-1. Investigate the discrepancy.
-2. Trust the source.
-3. Correct the map.
-
-Never propagate stale context. Never edit source code to match the map \u2014 you
-never edit source code at all.
-
-# Confidence
-
-Do not record assumptions as facts. If something is uncertain, mark it inline:
-
-> Confidence: low \u2014 inferred from \`src/foo.ts\` naming only
-
-Intent is the most common thing code cannot tell you. A single \`export { app }\`
-does not prove a test seam was intended, and one carefully written expression
-does not prove a repository convention. Mark those inferences or leave them
-out.
-
-If a fact cannot be established with reasonable effort, omit it. A short map
-that is true beats a long map that is partly guesswork.
-
-# Keep it small
-
-The context system exists to REDUCE context consumption. Never let the map
-grow into an encyclopedia. Do not write:
-
-- file inventories or directory listings
-- copied or paraphrased source code
-- large API descriptions
-- content duplicated from the project's own docs \u2014 link to them instead
-- generated documentation
-- exhaustive class or function lists
-- the same finding restated in several files \u2014 state a fact once, in the file
-  that owns it, and let the others point at it
-- generic programming advice that would be true in any repository
-
-Write conclusions, not inventories. Prefer a statement like
-"\`OrderService\` is the application boundary for order mutations" over a
-description of every method it exposes.
-
-If a file grows past its target, consolidate: merge overlapping entries, drop
-the lowest-value ones, and link out to authoritative project docs.
-
-# Review mode
-
-Trigger: an explicit review (see the \`context-review\` command).
-
-Audit the map files and the backlog for:
-
-- stale information \u2014 verify claims against the code
-- contradictions between files, or between the map and the code
-- excessive size \u2014 consolidate toward the targets above
-- duplicated information \u2014 one canonical place per fact
-- missing canonical entry points for significant subsystems
-- unsupported assumptions \u2014 anything unmarked that you cannot verify
-- backlog tasks that are finished but carry no date \u2014 the retention window
-  cannot age those out, so they stay forever
-
-Fix problems only in the files you own. Never modify source code during a
-review. Report what you found, what you fixed, and what you could not
-verify.
-
-# Reporting
-
-Finish with a short report:
-
-- what you inspected
-- what you created or changed, and why it matters for future agents
-- what you deliberately left out
-- anything you found that contradicts the code or the existing docs`,
+    prompt: CARTOGRAPHER_PROMPT,
     permission: {
       "read": "allow",
       "glob": "allow",
@@ -1624,11 +1748,14 @@ your system prompt.
 Otherwise follow the bootstrap procedure in your system prompt: progressive
 exploration (README \u2192 existing docs \u2192 manifests \u2192 top-level structure \u2192 build
 and framework config \u2192 entry points \u2192 selective source), then write the five
-context files inside their size targets. Also create
-\`.opencode/context/active.md\` with its heading and no tasks.
+context files inside their line budgets, using the entry schema (provenance
+marker, rule of at most three lines, \`\u2014 See <path>[ \xA7Section] (verified
+YYYY-MM-DD)\`). Also create \`.opencode/context/active.md\` with its heading and no
+tasks.
 
-Remember: write conclusions, not inventories. Link to the project's existing
-documentation instead of duplicating it.
+Remember: write conclusions, not inventories. Point at the project's existing
+documentation instead of restating it. Run the drift pass and report a
+contradiction rather than silently choosing a side.
 
 Report what you created or updated, what you deliberately left out, and
 anything that contradicts the code or existing docs.`
@@ -1654,7 +1781,11 @@ or an invariant not yet recorded.
 
 Do not edit documentation just because source files changed. No
 timestamp-only edits. If nothing material changed, make no edits and report
-"no update needed".`
+"no update needed".
+
+Every new or changed entry uses the schema in your system prompt and stays
+under the file's line budget. If a file is already over budget, consolidate
+before adding.`
   },
   "context-review": {
     description: "Audit .opencode/context/ for staleness, contradictions, excess size, duplication, and missing entry points.",
@@ -1662,20 +1793,29 @@ timestamp-only edits. If nothing material changed, make no edits and report
     subtask: true,
     template: `Context review.
 
-Everything outside \`.opencode/context/\` is read-only for this run. Do not
-modify source code under any circumstances.
+Follow the review procedure and entry schema in your system prompt. Everything
+outside \`.opencode/context/\` is read-only for this run. Do not modify source
+code under any circumstances.
 
 Audit the context files and the backlog for:
 
-- stale information \u2014 verify claims against the actual code
-- contradictions between context files, or between the map and the code
-- excessive size \u2014 consolidate toward the per-file targets in your system
-  prompt
+- schema \u2014 every entry has one provenance marker, at most three lines, a
+  pointer, and a \`(verified YYYY-MM-DD)\` date
+- budget \u2014 every file is within its non-blank-line cap; consolidate rather
+  than exceed it
+- stale information \u2014 verify claims against the actual code and the cited page
+- contradictions between context files, or between the map and a page \u2014 mark
+  \`[disputed]\` and report both sides; never silently prefer one
+- dangling pointers \u2014 every cited path and \xA7section must exist
+- unarchived content \u2014 an entry with no source in the tree; report it and keep
+  it, because it may be the only copy
+- restatement \u2014 a table, a fenced block, or a long verbatim span copied from a
+  page
 - duplicated information \u2014 one canonical place per fact; link to the
   project's own docs rather than restating them
 - missing canonical entry points for significant subsystems
-- unsupported assumptions \u2014 anything stated as fact that you cannot verify,
-  or that lacks a confidence marker
+- unsupported assumptions \u2014 anything that is not \`[binding]\` or \`[disputed]\`
+  should be \`[provisional]\`
 - backlog tasks that are finished but carry no date \u2014 the retention window
   cannot age those out, so they stay forever
 
@@ -1816,9 +1956,9 @@ function compareSemver(a, b) {
   }
   return 0;
 }
-function readInstalledVersion(packageRoot, read = (path4) => {
+function readInstalledVersion(packageRoot, read = (path5) => {
   try {
-    return readFileSync3(path4, "utf8");
+    return readFileSync3(path5, "utf8");
   } catch {
     return void 0;
   }
@@ -1876,17 +2016,17 @@ async function fetchLatest(fetchImpl = fetch, timeoutMs = FETCH_TIMEOUT_MS) {
     clearTimeout(timer);
   }
 }
-function readState(path4 = STATE_PATH) {
+function readState(path5 = STATE_PATH) {
   try {
-    return JSON.parse(readFileSync3(path4, "utf8"));
+    return JSON.parse(readFileSync3(path5, "utf8"));
   } catch {
     return {};
   }
 }
-function writeState(state2, path4 = STATE_PATH) {
+function writeState(state2, path5 = STATE_PATH) {
   try {
-    mkdirSync2(dirname2(path4), { recursive: true });
-    writeFileSync2(path4, JSON.stringify(state2));
+    mkdirSync2(dirname2(path5), { recursive: true });
+    writeFileSync2(path5, JSON.stringify(state2));
   } catch {
   }
 }
@@ -1899,39 +2039,39 @@ var isProcessAlive = (pid) => {
     return error.code === "EPERM";
   }
 };
-function acquireLock(path4 = LOCK_PATH, now = Date.now()) {
+function acquireLock(path5 = LOCK_PATH, now = Date.now()) {
   const claim = () => {
-    const fd = openSync(path4, "wx");
+    const fd = openSync(path5, "wx");
     writeSync(fd, String(process.pid));
     closeSync(fd);
     return () => {
       try {
-        unlinkSync2(path4);
+        unlinkSync2(path5);
       } catch {
       }
     };
   };
   try {
-    mkdirSync2(dirname2(path4), { recursive: true });
+    mkdirSync2(dirname2(path5), { recursive: true });
     return claim();
   } catch {
     let orphaned = false;
     try {
-      const pid = Number.parseInt(readFileSync3(path4, "utf8").trim(), 10);
+      const pid = Number.parseInt(readFileSync3(path5, "utf8").trim(), 10);
       orphaned = !Number.isFinite(pid) || pid <= 0 || !isProcessAlive(pid);
     } catch {
       orphaned = true;
     }
     if (!orphaned) {
       try {
-        orphaned = now - statSync2(path4).mtimeMs > LOCK_STALE_MS;
+        orphaned = now - statSync2(path5).mtimeMs > LOCK_STALE_MS;
       } catch {
         orphaned = true;
       }
     }
     if (!orphaned) return void 0;
     try {
-      unlinkSync2(path4);
+      unlinkSync2(path5);
     } catch {
       return void 0;
     }
@@ -2090,12 +2230,12 @@ var probeOne = async (client, opts, model, leftSeconds) => {
     const timeoutMs = opts.timeoutMs ?? PROBE_TIMEOUT_MS;
     const clock = opts.now ?? Date.now;
     let timedOut = false;
-    const deadline = new Promise((resolve3) => {
+    const deadline = new Promise((resolve4) => {
       timer = setTimeout(() => {
         timedOut = true;
         void client.session.abort({ path: { id: created }, query: { directory } }).catch(() => {
         });
-        resolve3(void 0);
+        resolve4(void 0);
       }, timeoutMs);
     });
     const answer = client.session.prompt({
@@ -2823,9 +2963,9 @@ two ordered passes in slot order: pass 1 fills each slot to its weight, pass 2 t
 });
 
 // src/plugins/context-autoupdate.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync5, statSync as statSync3, unlinkSync as unlinkSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync6, statSync as statSync4, unlinkSync as unlinkSync3, writeFileSync as writeFileSync4 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import * as path2 from "node:path";
+import * as path3 from "node:path";
 
 // src/lib/active-backlog.ts
 var ACTIVE_BACKLOG_FILE = "active.md";
@@ -2927,6 +3067,494 @@ var normalizeBacklog = (text, now = Date.now()) => {
   return { text: renderBacklog(kept), removed };
 };
 
+// src/lib/map-schema.ts
+import { existsSync as existsSync2, readFileSync as readFileSync4, statSync as statSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import * as path from "node:path";
+var PROVISIONAL_DAYS = 30;
+var MAP_SPECS = [
+  {
+    file: "architecture.md",
+    charter: "cross-subsystem structure: layers, boundaries, entry points, dependency rules",
+    budget: 150,
+    minEntries: 4,
+    kind: "entries",
+    provisionalDays: PROVISIONAL_DAYS,
+    sectionRequired: true
+  },
+  {
+    file: "contexts.md",
+    charter: "subsystem boundaries: purpose, start-here files, what must not change",
+    budget: 200,
+    minEntries: 3,
+    kind: "entries",
+    provisionalDays: PROVISIONAL_DAYS,
+    sectionRequired: true
+  },
+  {
+    file: "conventions.md",
+    charter: "rules to follow before writing code",
+    budget: 150,
+    minEntries: 3,
+    kind: "entries",
+    provisionalDays: PROVISIONAL_DAYS,
+    sectionRequired: true
+  },
+  {
+    file: "workflows.md",
+    charter: "runtime behaviour worth tracing",
+    budget: 150,
+    minEntries: 2,
+    kind: "entries",
+    provisionalDays: PROVISIONAL_DAYS,
+    sectionRequired: true
+  },
+  {
+    file: "decisions.md",
+    charter: "architectural constraints that bind future work",
+    budget: 120,
+    minEntries: 1,
+    kind: "entries",
+    provisionalDays: PROVISIONAL_DAYS,
+    sectionRequired: true
+  },
+  {
+    file: ACTIVE_BACKLOG_FILE,
+    charter: "work in flight, grouped by the ISO week it was opened",
+    budget: 60,
+    minEntries: 0,
+    kind: "backlog",
+    provisionalDays: PROVISIONAL_DAYS,
+    sectionRequired: false
+  }
+];
+var MAP_SPEC_BY_FILE = new Map(MAP_SPECS.map((spec) => [spec.file, spec]));
+var MAP_FILES = MAP_SPECS.map((spec) => spec.file);
+var NAVIGATION_FILES = MAP_SPECS.filter((spec) => spec.kind === "entries").map((spec) => spec.file);
+var DAY_MS2 = 24 * 60 * 60 * 1e3;
+var ENTRY_START = /^([-*+])\s+\[(binding|provisional|disputed)\]\s+(.*)$/i;
+var CONTINUATION = /^\s{2,}\S/;
+var LIST_ITEM = /^\s*(?:[-*+]|\d+[.)])\s+/;
+var FENCE = /^\s*(?:```|~~~)/;
+var TABLE_ROW = /^\s*\|.*\|\s*$/;
+var TABLE_SEPARATOR = /^\s*\|[\s:|-]*-{3,}[\s:|-]*\|\s*$/;
+var VERIFIED = /\(verified\s+(\d{4}-\d{2}-\d{2})\)\s*$/i;
+var POINTER = /(?:—|–|→|->)\s*See\s+`([^`\n]+)`(?:\s*§\s*([^()\n]+?))?(?:\s*\(verified\s+(\d{4}-\d{2}-\d{2})\))?\s*$/i;
+var DECISION_RECORD = /^\s*(?:#{1,6}\s*)?(?:\*\*)?(Context|Decision|Consequences|Alternatives|Status|Trade-?offs|Rationale)(?:\*\*)?\s*(?::|$)/im;
+var ARCHIVE_LANGUAGE = /\b(?:archive\s+of\s+record|this\s+(?:is|file\s+is|map\s+is)\s+the\s+only\s+(?:copy|record)|the\s+only\s+place\s+[^.\n]{0,80}?\b(?:remains|survives)\b|the\s+only\s+(?:copy|record)\s+[^.\n]{0,80}?\b(?:remains|survives|is\s+kept)\b|(?:survives|remains|is\s+kept)\s+only\s+here|no\s+longer\s+exists\s+(?:in|anywhere)|exists\s+only\s+(?:in|here))\b/i;
+var isCalendarDate2 = (value) => {
+  const at = Date.parse(`${value}T00:00:00Z`);
+  return Number.isFinite(at) && new Date(at).toISOString().slice(0, 10) === value;
+};
+var normalizeHeading = (value) => value.toLowerCase().replace(/[`*_]/g, "").replace(/^\s*\d+(?:\.\d+)*[.)]?\s*/, "").replace(/[^a-z0-9]+/g, " ").trim();
+var normalizeRule = (value) => value.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+var truncate = (value, max = 90) => value.length <= max ? value : `${value.slice(0, max - 1)}\u2026`;
+var parseMapEntries = (text) => {
+  const lines = text.split(/\r?\n/);
+  const entries = [];
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (FENCE.test(lines[i])) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const start = ENTRY_START.exec(lines[i]);
+    if (!start) continue;
+    const bodyLines = [start[3]];
+    let j = i + 1;
+    while (j < lines.length && CONTINUATION.test(lines[j]) && !FENCE.test(lines[j])) {
+      bodyLines.push(lines[j].trim());
+      j++;
+    }
+    const body = bodyLines.join("\n");
+    const flat = body.replace(/\s+/g, " ").trim();
+    const pointerMatch = POINTER.exec(flat);
+    const verifiedMatch = VERIFIED.exec(flat);
+    const pointer = pointerMatch?.[1]?.trim();
+    const section = pointerMatch?.[2]?.trim() || void 0;
+    const verified = pointerMatch?.[3] ?? verifiedMatch?.[1];
+    const rule = flat.replace(POINTER, "").replace(VERIFIED, "").trim();
+    entries.push({
+      startLine: i,
+      endLine: j,
+      marker: start[2].toLowerCase(),
+      body,
+      rule,
+      lineCount: bodyLines.filter((line) => line.trim()).length,
+      ...pointer ? { pointer } : {},
+      ...section ? { section } : {},
+      ...verified ? { verified } : {}
+    });
+    i = j - 1;
+  }
+  return entries;
+};
+var stripLineSuffix = (pointer) => pointer.replace(/[\\/]$/, "").replace(/(?::\d+(?:-\d+)?|#L\d+(?:-L?\d+)?)$/i, "");
+var headingOf = (line) => {
+  const match = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+  if (!match) return void 0;
+  return { level: match[1].length, text: match[2] };
+};
+var sectionText = (text, section) => {
+  const lines = text.split(/\r?\n/);
+  const wanted = normalizeHeading(section);
+  if (!wanted) return void 0;
+  for (let i = 0; i < lines.length; i++) {
+    const heading = headingOf(lines[i]);
+    if (!heading) continue;
+    const normalized = normalizeHeading(heading.text);
+    if (!(normalized === wanted || normalized.includes(wanted) || wanted.includes(normalized))) continue;
+    let end = lines.length;
+    for (let j = i + 1; j < lines.length; j++) {
+      const next = headingOf(lines[j]);
+      if (next && next.level <= heading.level) {
+        end = j;
+        break;
+      }
+    }
+    return lines.slice(i + 1, end).join("\n");
+  }
+  return void 0;
+};
+var resolvePointer = (root, pointer, section) => {
+  const cleaned = stripLineSuffix(pointer.trim().replace(/^`|`$/g, ""));
+  if (!cleaned) return { exists: false };
+  const absolute = path.resolve(root, cleaned);
+  const rootWithSep = root.endsWith(path.sep) ? root : root + path.sep;
+  if (absolute !== root && !absolute.startsWith(rootWithSep)) return { exists: false };
+  let stat;
+  try {
+    stat = statSync3(absolute);
+  } catch {
+    return { exists: false };
+  }
+  if (!stat.isFile()) return { exists: false };
+  let text;
+  try {
+    if (stat.size <= 512 * 1024) text = readFileSync4(absolute, "utf8");
+  } catch {
+    text = void 0;
+  }
+  if (section && text !== void 0) {
+    const found = sectionText(text, section);
+    return {
+      absolute,
+      exists: true,
+      mtimeMs: stat.mtimeMs,
+      sectionFound: found !== void 0,
+      ...found !== void 0 ? { sectionText: found } : {},
+      sourceText: found ?? text
+    };
+  }
+  return { absolute, exists: true, mtimeMs: stat.mtimeMs, ...text !== void 0 ? { sourceText: text } : {} };
+};
+var words = (value) => value.toLowerCase().replace(/[`*_[\]()]/g, " ").split(/[^a-z0-9]+/).filter((word) => word.length > 0);
+var STOPWORDS = /* @__PURE__ */ new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "that",
+  "this",
+  "from",
+  "are",
+  "was",
+  "were",
+  "has",
+  "have",
+  "had",
+  "not",
+  "never",
+  "none",
+  "into",
+  "onto",
+  "than",
+  "then",
+  "when",
+  "where",
+  "which",
+  "what",
+  "who",
+  "will",
+  "would",
+  "can",
+  "could",
+  "must",
+  "may",
+  "might",
+  "its",
+  "their",
+  "your",
+  "our",
+  "you",
+  "they",
+  "them",
+  "there",
+  "here",
+  "only",
+  "also",
+  "but",
+  "all",
+  "any",
+  "each",
+  "every",
+  "more",
+  "most",
+  "some",
+  "such",
+  "one",
+  "two",
+  "use",
+  "used",
+  "using",
+  "via",
+  "per",
+  "out",
+  "own"
+]);
+var contentWords = (value) => words(value).filter((word) => word.length >= 4 && !STOPWORDS.has(word));
+var ngrams = (values, size) => {
+  const out = /* @__PURE__ */ new Set();
+  for (let i = 0; i + size <= values.length; i++) out.add(values.slice(i, i + size).join(" "));
+  return out;
+};
+var hasNegation = (value) => /\b(?:not|never|none|no\s+longer|refuted|unsupported|absent|missing|removed|without)\b/i.test(value);
+var STATE_AUXILIARY = /\b(?:is|are|was|were|has|have|had|does|do|can|could)\b/i;
+var numbersIn = (value) => (value.match(/\b\d+(?:[.,]\d+)?\b/g) ?? []).map((number) => number.replace(/,/g, ""));
+var sharesVerbatimRun = (rule, source) => {
+  const entryWords = words(rule);
+  if (entryWords.length < 12) return false;
+  const sourceGrams = ngrams(words(source), 12);
+  for (const gram of ngrams(entryWords, 12)) if (sourceGrams.has(gram)) return true;
+  return false;
+};
+var possibleNegationConflict = (rule, source) => {
+  if (hasNegation(rule)) return void 0;
+  const entryWords = new Set(contentWords(rule));
+  if (entryWords.size < 3) return void 0;
+  const sentences = source.split(/(?:[.!?]\s+|\n+)/);
+  for (const sentence of sentences) {
+    if (!hasNegation(sentence) || !STATE_AUXILIARY.test(sentence)) continue;
+    const sentenceWords = new Set(contentWords(sentence));
+    if (sentenceWords.size === 0) continue;
+    let overlap = 0;
+    for (const word of entryWords) if (sentenceWords.has(word)) overlap++;
+    const ratio = overlap / Math.min(entryWords.size, sentenceWords.size);
+    if (overlap >= 3 && ratio >= 0.5) return truncate(sentence.trim());
+  }
+  return void 0;
+};
+var invalidNumbers = (rule, source) => {
+  const claimed = [...new Set(numbersIn(rule))];
+  if (claimed.length === 0) return [];
+  const sourceNumbers = new Set(numbersIn(source));
+  return claimed.filter((number) => !sourceNumbers.has(number));
+};
+var validateMapText = (spec, text, options) => {
+  const violations = [];
+  const lines = text.split(/\r?\n/);
+  const nonBlank = lines.filter((line) => line.trim()).length;
+  const push = (kind, detail, line) => violations.push({ file: spec.file, kind, detail, ...line !== void 0 ? { line: line + 1 } : {} });
+  if (nonBlank === 0) push("charter", `empty file; charter is ${spec.charter}`);
+  if (nonBlank > spec.budget) {
+    push("budget", `${nonBlank} non-blank lines exceeds the ${spec.budget}-line budget; consolidate, do not pad`);
+  }
+  if (spec.kind === "backlog") {
+    if (!text.startsWith("# ")) push("charter", "active backlog must start with a top-level heading");
+    return { spec, lines: nonBlank, entries: [], violations };
+  }
+  const entries = parseMapEntries(text);
+  let inFence = false;
+  let tableReported = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (FENCE.test(lines[i])) {
+      if (!inFence) push("restatement", "fenced code block; the map cites the file that owns the code, it does not copy it", i);
+      inFence = !inFence;
+      continue;
+    }
+    if (!inFence && !tableReported && (TABLE_ROW.test(lines[i]) || TABLE_SEPARATOR.test(lines[i]))) {
+      push("restatement", "table; a table belongs on the page that owns it, not in the map", i);
+      tableReported = true;
+    }
+  }
+  const record = DECISION_RECORD.exec(text);
+  if (record) {
+    push("schema", `decision-record block (${record[1]}); state only the operative constraint and its pointer`);
+  }
+  if (ARCHIVE_LANGUAGE.test(text)) {
+    push("archive", "the map claims to be an archive or the only copy; derived content must never be the archive of record");
+  }
+  const entryStarts = new Set(entries.map((entry) => entry.startLine));
+  inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (FENCE.test(lines[i])) {
+      inFence = !inFence;
+      continue;
+    }
+    if (!inFence && LIST_ITEM.test(lines[i]) && !entryStarts.has(i)) {
+      push("schema", "unmarked list item; every entry starts with - [binding], - [provisional] or - [disputed]", i);
+    }
+  }
+  let binding = 0;
+  for (const entry of entries) {
+    const line = entry.startLine;
+    if (entry.marker === "binding") binding++;
+    if (entry.lineCount > 3) {
+      push("schema", `entry is ${entry.lineCount} lines; the rule must fit in one to three`, line);
+    }
+    if (!entry.verified) {
+      push("schema", "entry has no (verified YYYY-MM-DD); the lifecycle and drift checks need it", line);
+    } else if (!isCalendarDate2(entry.verified)) {
+      push("schema", `verified date ${entry.verified} is not a real calendar date`, line);
+    } else if (Date.parse(`${entry.verified}T00:00:00Z`) > (options.now ?? Date.now()) + DAY_MS2) {
+      push("schema", `verified date ${entry.verified} is more than a day in the future`, line);
+    }
+    if (!entry.pointer) {
+      push("schema", "entry has no `\u2014 See <path>` pointer; a fact with no home is not a map entry", line);
+      push("unarchived", "content has no resolvable source in the tree; report it, do not emit it as derived", line);
+      continue;
+    }
+    if (spec.sectionRequired && /\.md$/i.test(stripLineSuffix(entry.pointer)) && !entry.section) {
+      push("schema", `page citation \`${entry.pointer}\` needs a \xA7section; a page is cited, not restated`, line);
+    }
+    const resolved = resolvePointer(options.root, entry.pointer, entry.section);
+    if (!resolved.exists) {
+      push("dangling", `cites \`${entry.pointer}\`, which does not exist in the tree`, line);
+      push("unarchived", `no source for \`${entry.pointer}\`; keep the text and report it, never delete it`, line);
+      continue;
+    }
+    if (entry.section && resolved.sectionFound === false) {
+      push("drift", `cites \xA7${entry.section} in \`${entry.pointer}\`, but that section no longer exists`, line);
+      continue;
+    }
+    if (resolved.mtimeMs !== void 0 && entry.verified) {
+      const modified = new Date(resolved.mtimeMs).toISOString().slice(0, 10);
+      if (modified > entry.verified) {
+        push("drift", `\`${entry.pointer}\` changed on ${modified}, after this entry was verified on ${entry.verified}; re-verify it`, line);
+      }
+    }
+    if (resolved.sourceText !== void 0) {
+      const missing = invalidNumbers(entry.rule, resolved.sourceText);
+      if (missing.length > 0) {
+        push("drift", `numeric claim(s) ${missing.join(", ")} not found in \`${entry.pointer}\`; the map and the source may disagree`, line);
+      }
+      if (sharesVerbatimRun(entry.rule, resolved.sourceText)) {
+        push("restatement", `contains a long verbatim span from \`${entry.pointer}\`; cite the section instead`, line);
+      }
+      const conflict = possibleNegationConflict(entry.rule, resolved.sourceText);
+      if (conflict) {
+        push("drift", `possible contradiction with \`${entry.pointer}\`: "${conflict}"; verify, do not silently overwrite either side`, line);
+      }
+    }
+  }
+  if (entries.length < spec.minEntries) {
+    push("charter", `${entries.length} entr${entries.length === 1 ? "y" : "ies"} is degenerate for ${spec.charter}`);
+  } else if (entries.length > 0 && binding === 0) {
+    push("charter", "every entry is provisional or disputed; a navigation file must carry at least one binding constraint");
+  }
+  return { spec, lines: nonBlank, entries, violations };
+};
+var normalizeMapText = (spec, text, options = {}) => {
+  const now = options.now ?? Date.now();
+  if (spec.kind === "backlog") {
+    const result = normalizeBacklog(text, now);
+    return {
+      text: result.text,
+      removed: result.removed.map((title) => ({ line: 0, text: title })),
+      kept: 0
+    };
+  }
+  const entries = parseMapEntries(text);
+  const drop = /* @__PURE__ */ new Set();
+  const removed = [];
+  for (const entry of entries) {
+    if (entry.marker !== "provisional") continue;
+    if (!entry.verified || !entry.pointer) continue;
+    if (options.canResolve && !options.canResolve(entry.pointer, entry.section)) continue;
+    const at = Date.parse(`${entry.verified}T00:00:00Z`);
+    if (!Number.isFinite(at)) continue;
+    if (now - at <= spec.provisionalDays * DAY_MS2) continue;
+    for (let i = entry.startLine; i < entry.endLine; i++) drop.add(i);
+    removed.push({ line: entry.startLine + 1, text: truncate(entry.rule) });
+  }
+  if (removed.length === 0) return { text, removed, kept: entries.length };
+  const keptLines = text.split(/\r?\n/).filter((_, index) => !drop.has(index));
+  const compact = keptLines.join("\n").replace(/\n{3,}/g, "\n\n");
+  const out = compact.endsWith("\n") ? compact : `${compact}
+`;
+  return { text: out, removed, kept: entries.length - removed.length };
+};
+var maintainMap = (root, mapDir, now = Date.now()) => {
+  const files = [];
+  let removedTotal = 0;
+  for (const spec of MAP_SPECS) {
+    const absolute = path.join(mapDir, spec.file);
+    if (!existsSync2(absolute)) continue;
+    let before;
+    try {
+      before = readFileSync4(absolute, "utf8");
+    } catch {
+      continue;
+    }
+    const canResolve = (pointer, section) => resolvePointer(root, pointer, section).exists;
+    const result = normalizeMapText(spec, before, { now, canResolve });
+    const changed = result.text !== before;
+    if (changed) writeFileSync3(absolute, result.text);
+    if (result.removed.length > 0) {
+      removedTotal += result.removed.length;
+      files.push({ file: spec.file, changed, removed: result.removed });
+    } else if (changed) {
+      files.push({ file: spec.file, changed, removed: [] });
+    }
+  }
+  return { files, removedTotal };
+};
+var auditMap = (root, mapDir, now = Date.now()) => {
+  const files = [];
+  const violations = [];
+  const rulesSeen = /* @__PURE__ */ new Map();
+  for (const spec of MAP_SPECS) {
+    const absolute = path.join(mapDir, spec.file);
+    if (!existsSync2(absolute)) {
+      const violation = { file: spec.file, kind: "missing-file", detail: `missing; charter is ${spec.charter}` };
+      violations.push(violation);
+      continue;
+    }
+    let text;
+    try {
+      text = readFileSync4(absolute, "utf8");
+    } catch {
+      violations.push({ file: spec.file, kind: "missing-file", detail: "unreadable" });
+      continue;
+    }
+    const result = validateMapText(spec, text, { root, now });
+    files.push(result);
+    violations.push(...result.violations);
+    if (spec.kind === "entries") {
+      for (const entry of result.entries) {
+        const key = normalizeRule(entry.rule);
+        if (key.length < 12) continue;
+        const home = rulesSeen.get(key);
+        if (home !== void 0 && home !== spec.file) {
+          violations.push({
+            file: spec.file,
+            line: entry.startLine + 1,
+            kind: "duplicate",
+            detail: `same rule is already stated in ${home}; one fact has one home`
+          });
+        } else if (home === void 0) {
+          rulesSeen.set(key, spec.file);
+        }
+      }
+    }
+  }
+  return { ok: violations.length === 0, files, violations };
+};
+var formatViolations = (violations, limit = 20) => violations.slice(0, limit).map((violation) => {
+  const where = violation.line !== void 0 ? `${violation.file}:${violation.line}` : violation.file;
+  return `${where} [${violation.kind}] ${violation.detail}`;
+});
+
 // src/lib/jsonc.ts
 var stripJsonc = (raw) => {
   let out = "";
@@ -2975,12 +3603,12 @@ var parseJsonc = (raw) => {
 };
 
 // src/lib/writer-rule.ts
-import { readFileSync as readFileSync4 } from "node:fs";
-import * as path from "node:path";
-var CONTEXT_DIR = path.join(".opencode", "context");
+import { readFileSync as readFileSync5 } from "node:fs";
+import * as path2 from "node:path";
+var CONTEXT_DIR = path2.join(".opencode", "context");
 var WRITER = "context";
 var INSTRUCTIONS_WRITER = AGENT_INSTRUCTIONS_WRITER;
-var toPosix = (value) => value.split(path.sep).join("/");
+var toPosix = (value) => value.split(path2.sep).join("/");
 var compilePattern = (pattern) => {
   const escaped = toPosix(pattern).replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
   return new RegExp(`^${escaped}$`, "s");
@@ -3005,17 +3633,17 @@ var readAgents = (raw) => {
 };
 var permissionOf = (agent) => agent?.permission?.edit;
 var evaluatedForm = (mapDir, projectRoot) => {
-  const absolute = toPosix(path.join(mapDir, "architecture.md"));
-  return projectRoot ? toPosix(path.relative(projectRoot, absolute)) : absolute;
+  const absolute = toPosix(path2.join(mapDir, "architecture.md"));
+  return projectRoot ? toPosix(path2.relative(projectRoot, absolute)) : absolute;
 };
 var agentsForm = (mapDir, projectRoot) => {
-  const absolute = toPosix(path.join(mapDir, "..", "..", "AGENTS.md"));
-  return projectRoot ? toPosix(path.relative(projectRoot, absolute)) : absolute;
+  const absolute = toPosix(path2.join(mapDir, "..", "..", "AGENTS.md"));
+  return projectRoot ? toPosix(path2.relative(projectRoot, absolute)) : absolute;
 };
 var verifyWriterRule = (configPath, mapDir, projectRoot) => {
   let raw;
   try {
-    raw = readFileSync4(configPath, "utf8");
+    raw = readFileSync5(configPath, "utf8");
   } catch {
     return void 0;
   }
@@ -3028,7 +3656,7 @@ var verifyWriterRule = (configPath, mapDir, projectRoot) => {
   const form = evaluatedForm(mapDir, projectRoot);
   if (rules.length > 0) {
     if (!rules.some((rule) => compilePattern(rule).test(form))) {
-      return `context map is not writable: none of the allow rules in ${path.basename(configPath)} match ` + (projectRoot ? `the project-root-relative form "${form}" that opencode actually evaluates for project root ${toPosix(projectRoot)}` : `the absolute form "${form}"`) + `. Rules seen: ${rules.map((r) => `"${r}"`).join(", ")}. opencode evaluates file permissions against the path RELATIVE TO THE PROJECT ROOT, so "${CONTEXT_DIR}/**" is what fires for a normally-rooted project while "*/${CONTEXT_DIR}/**" only fires when the project root is "/". Allow both forms.`;
+      return `context map is not writable: none of the allow rules in ${path2.basename(configPath)} match ` + (projectRoot ? `the project-root-relative form "${form}" that opencode actually evaluates for project root ${toPosix(projectRoot)}` : `the absolute form "${form}"`) + `. Rules seen: ${rules.map((r) => `"${r}"`).join(", ")}. opencode evaluates file permissions against the path RELATIVE TO THE PROJECT ROOT, so "${CONTEXT_DIR}/**" is what fires for a normally-rooted project while "*/${CONTEXT_DIR}/**" only fires when the project root is "/". Allow both forms.`;
     }
   }
   const agents = readAgents(raw);
@@ -3061,7 +3689,7 @@ var verifyWriterRule = (configPath, mapDir, projectRoot) => {
 
 // src/plugins/context-autoupdate.ts
 var SERVICE2 = "context-autoupdate";
-var CONTEXT_DIR2 = path2.join(".opencode", "context");
+var CONTEXT_DIR2 = path3.join(".opencode", "context");
 var COOLDOWN_MS = 10 * 60 * 1e3;
 var OWNED_TTL_MS = 20 * 60 * 1e3;
 var MAX_FILES_LISTED = 25;
@@ -3098,13 +3726,19 @@ var NO_BULK_READS = [
   "that PRODUCES or CONSUMES them instead. If a payload must be sampled, use",
   "`head -c 2000` or `wc -c` \u2014 never `cat` or a bare `grep -r` across one."
 ].join(" ");
-var toPosix2 = (value) => value.split(path2.sep).join("/");
+var ENTRY_CONTRACT = [
+  "Every navigation entry uses the schema in your system prompt:",
+  "`- [binding|provisional|disputed] <rule, at most three lines> \u2014 See `<path>`[ \xA7Section] (verified YYYY-MM-DD)`.",
+  "Stay inside each file's line budget. Point at the page or path that owns a fact; do not restate it.",
+  "After writing, run the drift pass: report a contradiction, never overwrite the page or silently pick a side."
+].join(" ");
+var toPosix2 = (value) => value.split(path3.sep).join("/");
 var findProjectConfig = () => {
-  let dir = import.meta.dir ?? path2.dirname(new URL(import.meta.url).pathname);
+  let dir = import.meta.dir ?? path3.dirname(new URL(import.meta.url).pathname);
   for (let up = 0; up <= 3; up++) {
-    const candidate = path2.join(dir, "opencode.jsonc");
-    if (existsSync2(candidate)) return candidate;
-    const parent = path2.dirname(dir);
+    const candidate = path3.join(dir, "opencode.jsonc");
+    if (existsSync3(candidate)) return candidate;
+    const parent = path3.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -3114,9 +3748,9 @@ var snapshotMap = (dir) => {
   const out = /* @__PURE__ */ new Map();
   try {
     for (const name of readdirSync2(dir)) {
-      const file = path2.join(dir, name);
+      const file = path3.join(dir, name);
       try {
-        const st = statSync3(file);
+        const st = statSync4(file);
         if (st.isFile()) out.set(name, `${st.size}:${st.mtimeMs}`);
       } catch {
       }
@@ -3133,20 +3767,20 @@ var changedSince = (before, dir) => {
   return changed;
 };
 var RETAIN_TRANSCRIPTS = 20;
-var transcriptDir = () => process.env.LACODE_TRANSCRIPT_DIR ?? path2.join(homedir3(), ".local", "share", "opencode", "lacode", "cartographer");
+var transcriptDir = () => process.env.LACODE_TRANSCRIPT_DIR ?? path3.join(homedir3(), ".local", "share", "opencode", "lacode", "cartographer");
 var retireSession = async (client, directory, sessionID, mode, log) => {
   try {
     const transcript = await client.session.messages({ path: { id: sessionID }, query: { directory } }).then((r) => r.data).catch(() => void 0);
     const dir = transcriptDir();
     mkdirSync3(dir, { recursive: true });
     const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-    const file = path2.join(dir, `${stamp}-${mode}.json`);
-    writeFileSync3(file, JSON.stringify({ sessionID, mode, messages: transcript ?? null }, null, 2));
+    const file = path3.join(dir, `${stamp}-${mode}.json`);
+    writeFileSync4(file, JSON.stringify({ sessionID, mode, messages: transcript ?? null }, null, 2));
     pruneTranscripts(dir);
     const gone = async () => await client.session.get({ path: { id: sessionID }, query: { directory } }).then((r) => r.data).catch(() => void 0) === void 0;
     await client.session.delete({ path: { id: sessionID }, query: { directory } }).catch(() => void 0);
     if (await gone()) return;
-    await new Promise((resolve3) => setTimeout(resolve3, 500));
+    await new Promise((resolve4) => setTimeout(resolve4, 500));
     await client.session.delete({ path: { id: sessionID }, query: { directory } }).catch(() => void 0);
     if (await gone()) return;
     await log?.("warn", "the cartographer's session could not be removed from the session list; it stays as an empty entry", {
@@ -3162,7 +3796,7 @@ var pruneTranscripts = (dir) => {
     const entries = readdirSync2(dir).filter((name) => name.endsWith(".json")).sort();
     for (const name of entries.slice(0, Math.max(0, entries.length - RETAIN_TRANSCRIPTS))) {
       try {
-        unlinkSync3(path2.join(dir, name));
+        unlinkSync3(path3.join(dir, name));
       } catch {
       }
     }
@@ -3176,24 +3810,24 @@ var contextAutoUpdateHooks = (async ({ client, directory }, options) => {
   const state2 = state(options);
   const log = (level, message, extra) => client.app.log({ body: { service: SERVICE2, level, message, extra } }).catch(() => {
   });
-  const root = path2.resolve(directory);
-  const contextAbs = path2.join(root, CONTEXT_DIR2);
-  const activeBacklogPath = path2.join(contextAbs, ACTIVE_BACKLOG_FILE);
+  const root = path3.resolve(directory);
+  const contextAbs = path3.join(root, CONTEXT_DIR2);
+  const activeBacklogPath = path3.join(contextAbs, ACTIVE_BACKLOG_FILE);
   const config = findProjectConfig();
   const writerProblem = config ? verifyWriterRule(config, contextAbs, root) : void 0;
   if (writerProblem) void log("error", writerProblem);
   const isTracked = (file) => {
-    const absolute = path2.resolve(root, file);
-    if (absolute !== root && !absolute.startsWith(root + path2.sep)) return false;
-    if (absolute === contextAbs || absolute.startsWith(contextAbs + path2.sep)) return false;
+    const absolute = path3.resolve(root, file);
+    if (absolute !== root && !absolute.startsWith(root + path3.sep)) return false;
+    if (absolute === contextAbs || absolute.startsWith(contextAbs + path3.sep)) return false;
     return !toPosix2(absolute).split("/").some((segment) => IGNORED_SEGMENTS.has(segment));
   };
   const normalizeActiveBacklog = async () => {
     try {
-      if (!existsSync2(activeBacklogPath)) return { removed: 0 };
-      const before = readFileSync5(activeBacklogPath, "utf8");
+      if (!existsSync3(activeBacklogPath)) return { removed: 0 };
+      const before = readFileSync6(activeBacklogPath, "utf8");
       const { text, removed } = normalizeBacklog(before);
-      if (text !== before) writeFileSync3(activeBacklogPath, text);
+      if (text !== before) writeFileSync4(activeBacklogPath, text);
       if (removed.length > 0) {
         await log("info", `active backlog: dropped ${removed.length} task(s) finished more than a week ago`, {
           removed: removed.length
@@ -3204,7 +3838,46 @@ var contextAutoUpdateHooks = (async ({ client, directory }, options) => {
       return { removed: 0 };
     }
   };
-  void normalizeActiveBacklog();
+  const applyLifecycle = async () => {
+    try {
+      const result = maintainMap(root, contextAbs);
+      for (const file of result.files) {
+        if (file.removed.length === 0) continue;
+        await log(
+          "info",
+          `map lifecycle: dropped ${file.removed.length} expired provisional entr${file.removed.length === 1 ? "y" : "ies"} from ${file.file}`,
+          { file: file.file, removed: file.removed.map((entry) => entry.text) }
+        );
+      }
+      return result;
+    } catch {
+      return void 0;
+    }
+  };
+  const reportMapAudit = async (mode) => {
+    try {
+      const audit = auditMap(root, contextAbs);
+      if (audit.ok) {
+        await log("info", "context map validation passed", { mode, files: audit.files.length });
+        return audit;
+      }
+      const byKind = {};
+      for (const violation of audit.violations) {
+        byKind[violation.kind] = (byKind[violation.kind] ?? 0) + 1;
+      }
+      await log("error", `context map validation failed: ${audit.violations.length} issue(s)`, {
+        mode,
+        byKind,
+        issues: formatViolations(audit.violations, 20),
+        note: "reported, not rewritten; fix the entry or its source and run /context-update"
+      });
+      return audit;
+    } catch (error) {
+      await log("warn", `context map validation could not run: ${String(error)}`, { mode });
+      return void 0;
+    }
+  };
+  void applyLifecycle();
   const listed = (files) => {
     const shown = files.slice(0, MAX_FILES_LISTED);
     const rest = files.length - shown.length;
@@ -3222,7 +3895,9 @@ var contextAutoUpdateHooks = (async ({ client, directory }, options) => {
     "",
     NO_BULK_READS,
     "",
-    "Follow the bootstrap procedure in your system prompt: progressive exploration, then write the five context files within their size targets. Also create `.opencode/context/active.md` with its heading and no tasks. When the project already has architecture or decision documentation, link to it instead of duplicating it. Write conclusions, not inventories."
+    ENTRY_CONTRACT,
+    "",
+    "Follow the bootstrap procedure in your system prompt: progressive exploration, then write the five context files within their line budgets. Also create `.opencode/context/active.md` with its heading and no tasks. When the project already has architecture or decision documentation, link to it instead of duplicating it. Write conclusions, not inventories."
   ].join("\n") : [
     "Incremental context update. Project root: " + directory,
     "",
@@ -3231,6 +3906,8 @@ var contextAutoUpdateHooks = (async ({ client, directory }, options) => {
     "",
     NO_BULK_READS,
     "",
+    ENTRY_CONTRACT,
+    "",
     'Follow the incremental-update procedure in your system prompt. Update a context file only if this work introduced or revealed information that will materially help future agents: a new boundary or module, a new or moved canonical entry point, a changed workflow, a new convention, an architectural decision, a new dependency between subsystems, a renamed or moved subsystem, or an invariant not yet recorded. Do not edit documentation merely because source files changed. If nothing material changed, make no edits and report "no update needed". Also keep `.opencode/context/active.md` current: record work that is in flight, and mark a task finished \u2014 with the date it finished \u2014 when it is.'
   ].join("\n");
   return {
@@ -3238,7 +3915,7 @@ var contextAutoUpdateHooks = (async ({ client, directory }, options) => {
       try {
         if (event.type === "file.edited") {
           const file = event.properties.file;
-          if (path2.resolve(root, file) === activeBacklogPath) {
+          if (path3.resolve(root, file) === activeBacklogPath) {
             await normalizeActiveBacklog();
             return;
           }
@@ -3265,7 +3942,7 @@ var contextAutoUpdateHooks = (async ({ client, directory }, options) => {
         const requeue = () => {
           for (const file of files) pending.add(file);
         };
-        const mode = existsSync2(path2.join(contextAbs, "contexts.md")) ? "update" : "bootstrap";
+        const mode = existsSync3(path3.join(contextAbs, "contexts.md")) ? "update" : "bootstrap";
         init(state2, (m) => void log("warn", m));
         const snap = snapshot(state2);
         const slot = pickSlot(state2, snap);
@@ -3332,6 +4009,13 @@ var contextAutoUpdateHooks = (async ({ client, directory }, options) => {
               hint: "either nothing needed updating, or the cartographer could not write -- check the one-writer permission rule"
             });
           }
+          await applyLifecycle();
+          const audit = await reportMapAudit(mode);
+          if (audit && !audit.ok) {
+            await log("error", `auto ${mode} finished with ${audit.violations.length} map validation issue(s)`, {
+              sessionID: target
+            });
+          }
         }).catch(async (error) => {
           release(state2, claimKey2);
           await retireSession(client, directory, target, mode, log);
@@ -3345,11 +4029,92 @@ var contextAutoUpdateHooks = (async ({ client, directory }, options) => {
   };
 });
 
+// src/lib/feedback.ts
+import { mkdirSync as mkdirSync4, readFileSync as readFileSync7, renameSync as renameSync3, unlinkSync as unlinkSync4, writeFileSync as writeFileSync5 } from "node:fs";
+import { homedir as homedir4 } from "node:os";
+import { dirname as dirname4, join as join7 } from "node:path";
+var FEEDBACK_HINT_ENV = "LACODE_NO_FEEDBACK_HINT";
+var FEEDBACK_HINT = "Enjoying lacode? Bugs, ideas, or a quick note on how you use it: github.com/lawaty/lacode/issues (a \u2B50 on the repo helps others find it)";
+var feedbackStatePath = () => join7(homedir4(), ".local", "share", "opencode", "lacode", "feedback.json");
+function readFeedbackState(path5 = feedbackStatePath()) {
+  try {
+    const parsed = JSON.parse(readFileSync7(path5, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return void 0;
+    return parsed;
+  } catch (error) {
+    if (error?.code === "ENOENT") return {};
+    return void 0;
+  }
+}
+function markFeedbackHintShown(path5 = feedbackStatePath()) {
+  try {
+    mkdirSync4(dirname4(path5), { recursive: true });
+    const tmp = `${path5}.${process.pid}.tmp`;
+    writeFileSync5(tmp, JSON.stringify({ feedbackHintShown: true }));
+    renameSync3(tmp, path5);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function restoreFeedbackState(path5 = feedbackStatePath(), previous = {}) {
+  try {
+    if (Object.keys(previous).length === 0) {
+      unlinkSync4(path5);
+      return;
+    }
+    const tmp = `${path5}.${process.pid}.tmp`;
+    writeFileSync5(tmp, JSON.stringify(previous));
+    renameSync3(tmp, path5);
+  } catch {
+  }
+}
+async function maybeShowFeedbackHint(deps = {}) {
+  const env = deps.env ?? process.env;
+  if (deps.enabled === false || deps.feedbackHint === false) return "disabled";
+  if (env[FEEDBACK_HINT_ENV] === "1") return "disabled";
+  const interactive = deps.interactive ?? process.stdout.isTTY === true;
+  if (!interactive || env.CI || env.NODE_TEST_CONTEXT) return "unavailable";
+  if (!deps.show) return "unavailable";
+  const state2 = readFeedbackState(deps.statePath);
+  if (state2 === void 0 || state2.feedbackHintShown === true) return "skipped";
+  if (!markFeedbackHintShown(deps.statePath)) return "skipped";
+  try {
+    await deps.show(FEEDBACK_HINT);
+  } catch {
+    restoreFeedbackState(deps.statePath, state2);
+    return "skipped";
+  }
+  return "shown";
+}
+
+// src/plugins/feedback.ts
+async function feedbackHooks(input, options, deps = {}) {
+  const opts = options ?? {};
+  if (opts.enabled === false || opts.feedbackHint === false) return {};
+  const tui = input.client.tui;
+  const show = deps.show ?? (tui?.showToast ? async (message) => {
+    await tui.showToast({
+      body: { title: "lacode", message, variant: "info", duration: 8e3 }
+    });
+  } : void 0);
+  void maybeShowFeedbackHint({
+    enabled: opts.enabled,
+    feedbackHint: opts.feedbackHint,
+    env: deps.env,
+    statePath: deps.statePath,
+    interactive: deps.interactive,
+    show
+  }).catch(() => {
+  });
+  return {};
+}
+
 // src/plugins/image-paste.ts
 import { createHash, randomUUID } from "node:crypto";
-import { globSync, mkdirSync as mkdirSync4, readFileSync as readFileSync6, renameSync as renameSync3, statSync as statSync4, writeFileSync as writeFileSync4 } from "node:fs";
-import { homedir as homedir4 } from "node:os";
-import { basename as basename2, join as join6 } from "node:path";
+import { globSync, mkdirSync as mkdirSync5, readFileSync as readFileSync8, renameSync as renameSync4, statSync as statSync5, writeFileSync as writeFileSync6 } from "node:fs";
+import { homedir as homedir5 } from "node:os";
+import { basename as basename2, join as join8 } from "node:path";
 
 // src/lib/clipboard.ts
 import { spawnSync } from "node:child_process";
@@ -3410,12 +4175,12 @@ var WINDOWS_SCRIPT = [
 var readWindows = async (run) => {
   const result = await run("powershell", ["-NoProfile", "-NonInteractive", "-Command", WINDOWS_SCRIPT]);
   if (!result.ok) return null;
-  const path4 = result.stdout.toString("utf8").replace(/^\uFEFF/, "").trim();
-  if (!path4) return null;
+  const path5 = result.stdout.toString("utf8").replace(/^\uFEFF/, "").trim();
+  if (!path5) return null;
   try {
-    return validImage({ ok: true, stdout: await readFile(path4) });
+    return validImage({ ok: true, stdout: await readFile(path5) });
   } finally {
-    await rm(path4, { force: true }).catch(() => {
+    await rm(path5, { force: true }).catch(() => {
     });
   }
 };
@@ -3499,8 +4264,8 @@ function splitArguments(input) {
   return out;
 }
 function expandTilde(p) {
-  if (p === "~") return homedir4();
-  if (p.startsWith("~/")) return join6(homedir4(), p.slice(2));
+  if (p === "~") return homedir5();
+  if (p.startsWith("~/")) return join8(homedir5(), p.slice(2));
   return p;
 }
 function expandGlob(p) {
@@ -3515,11 +4280,11 @@ function storeImage(bytes, dir, sessionID, label) {
   const kind = detectImageKind(bytes);
   if (kind === null) return null;
   const hash = createHash("sha256").update(bytes).digest("hex");
-  mkdirSync4(dir, { recursive: true });
-  const target = join6(dir, `${hash}.${kind.ext}`);
+  mkdirSync5(dir, { recursive: true });
+  const target = join8(dir, `${hash}.${kind.ext}`);
   const tmp = `${target}.tmp`;
-  writeFileSync4(tmp, bytes, { mode: 384 });
-  renameSync3(tmp, target);
+  writeFileSync6(tmp, bytes, { mode: 384 });
+  renameSync4(tmp, target);
   const part = {
     id: randomUUID(),
     sessionID,
@@ -3547,7 +4312,7 @@ async function imagePasteHooks(input, options, deps) {
     if (opts.enabled === false) return {};
     const maxBytes = resolveMaxBytes(opts);
     const maxImages = resolveMaxImages(opts);
-    const dir = opts.dir ?? process.env.LACODE_IMAGE_DIR ?? join6(homedir4(), ".local/share/opencode/lacode/images");
+    const dir = opts.dir ?? process.env.LACODE_IMAGE_DIR ?? join8(homedir5(), ".local/share/opencode/lacode/images");
     const readClipboard = (deps ?? {}).readClipboard ?? readClipboardImage;
     return {
       "command.execute.before": async (cmd, output) => {
@@ -3588,7 +4353,7 @@ async function imagePasteHooks(input, options, deps) {
               const name = basename2(filePath);
               let size;
               try {
-                const stat = statSync4(filePath);
+                const stat = statSync5(filePath);
                 if (!stat.isFile()) {
                   skipped.push(name);
                   continue;
@@ -3604,7 +4369,7 @@ async function imagePasteHooks(input, options, deps) {
               }
               let bytes;
               try {
-                bytes = readFileSync6(filePath);
+                bytes = readFileSync8(filePath);
               } catch {
                 skipped.push(name);
                 continue;
@@ -3662,13 +4427,14 @@ function scrubSlotNames(text) {
 
 // src/plugins/notify.ts
 import { spawn as spawn2 } from "node:child_process";
-import { existsSync as existsSync3 } from "node:fs";
-import * as path3 from "node:path";
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { existsSync as existsSync4 } from "node:fs";
+import * as path4 from "node:path";
 
 // src/lib/notify.ts
-import { closeSync as closeSync2, mkdirSync as mkdirSync5, openSync as openSync2, readFileSync as readFileSync7, renameSync as renameSync4, statSync as statSync5, unlinkSync as unlinkSync4, writeFileSync as writeFileSync5, writeSync as writeSync2 } from "node:fs";
-import { homedir as homedir5 } from "node:os";
-import { basename as basename3, join as join7 } from "node:path";
+import { closeSync as closeSync2, mkdirSync as mkdirSync6, openSync as openSync2, readFileSync as readFileSync9, renameSync as renameSync5, statSync as statSync6, unlinkSync as unlinkSync5, writeFileSync as writeFileSync7, writeSync as writeSync2 } from "node:fs";
+import { homedir as homedir6 } from "node:os";
+import { basename as basename3, join as join9 } from "node:path";
 var INTERNAL_TITLE_PREFIXES = [
   // context-autoupdate spawns the cartographer through the session API, with no
   // parentID, so it looks exactly like a root session going idle. Notifying for
@@ -3845,7 +4611,7 @@ var Notifier = class {
     return this.lastSent.size;
   }
 };
-var notificationStateDir = () => process.env.LACODE_NOTIFY_DIR ?? join7(homedir5(), ".local", "share", "opencode", "lacode", "notify");
+var notificationStateDir = () => process.env.LACODE_NOTIFY_DIR ?? join9(homedir6(), ".local", "share", "opencode", "lacode", "notify");
 var safeCorrelationKey = (correlationKey) => correlationKey.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 64);
 var CLAIM_WINDOW_MS = 5e3;
 var isPidAlive2 = (pid) => {
@@ -3856,19 +4622,19 @@ var isPidAlive2 = (pid) => {
     return error.code === "EPERM";
   }
 };
-var claimFile = (sessionID, kind) => join7(notificationStateDir(), `claim.${safeCorrelationKey(`${sessionID}.${kind}`)}`);
-var claimNotification = (sessionID, kind) => {
-  const path4 = claimFile(sessionID, kind);
+var claimFile = (sessionID, kind) => join9(notificationStateDir(), `claim.${safeCorrelationKey(`${sessionID}.${kind}`)}`);
+var claimNotification = (sessionID, kind, instanceId = "") => {
+  const path5 = claimFile(sessionID, kind);
   try {
-    mkdirSync5(notificationStateDir(), { recursive: true });
+    mkdirSync6(notificationStateDir(), { recursive: true });
   } catch {
     return true;
   }
   const take = () => {
     try {
-      const fd = openSync2(path4, "wx");
+      const fd = openSync2(path5, "wx");
       try {
-        writeSync2(fd, String(process.pid));
+        writeSync2(fd, `${process.pid} ${instanceId} ${kind}`);
       } finally {
         closeSync2(fd);
       }
@@ -3884,20 +4650,28 @@ var claimNotification = (sessionID, kind) => {
   const judge = () => {
     let raw;
     try {
-      raw = readFileSync7(path4, "utf8").trim();
+      raw = readFileSync9(path5, "utf8").trim();
     } catch (error) {
       return error.code === "ENOENT" ? "gone" : "unknown";
     }
+    const fields = raw.split(/\s+/).filter((entry) => entry.length > 0);
     let holder;
     const empty = raw === "";
     if (!empty) {
-      const parsed = Number.parseInt(raw, 10);
+      const parsed = Number.parseInt(fields[0] ?? "", 10);
       holder = Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
     }
-    if (holder === process.pid) return "ours";
+    if (holder === process.pid) {
+      const hasToken = fields.length >= 3;
+      const fileToken = hasToken ? fields[1] ?? "" : "";
+      if (hasToken && instanceId !== "" && fileToken !== instanceId) {
+        return "held";
+      }
+      return "ours";
+    }
     let age = Number.POSITIVE_INFINITY;
     try {
-      age = Date.now() - statSync5(path4).mtimeMs;
+      age = Date.now() - statSync6(path5).mtimeMs;
     } catch {
       return "gone";
     }
@@ -3914,7 +4688,7 @@ var claimNotification = (sessionID, kind) => {
   if (judged === "held") return false;
   if (judged === "unknown") return true;
   if (judged === "gone") return take() !== "held";
-  const lockPath = `${path4}.takeover`;
+  const lockPath = `${path5}.takeover`;
   const takeOver = () => {
     const create = () => {
       try {
@@ -3926,7 +4700,7 @@ var claimNotification = (sessionID, kind) => {
         }
         return () => {
           try {
-            unlinkSync4(lockPath);
+            unlinkSync5(lockPath);
           } catch {
           }
         };
@@ -3940,9 +4714,9 @@ var claimNotification = (sessionID, kind) => {
     let lockHolder;
     let lockAge = Number.POSITIVE_INFINITY;
     try {
-      const parsed = Number.parseInt(readFileSync7(lockPath, "utf8").trim(), 10);
+      const parsed = Number.parseInt(readFileSync9(lockPath, "utf8").trim(), 10);
       lockHolder = Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
-      lockAge = Date.now() - statSync5(lockPath).mtimeMs;
+      lockAge = Date.now() - statSync6(lockPath).mtimeMs;
     } catch {
       return create();
     }
@@ -3950,7 +4724,7 @@ var claimNotification = (sessionID, kind) => {
       return void 0;
     }
     try {
-      unlinkSync4(lockPath);
+      unlinkSync5(lockPath);
     } catch {
       return void 0;
     }
@@ -3964,7 +4738,7 @@ var claimNotification = (sessionID, kind) => {
     if (current === "held") return false;
     if (current === "unknown") return true;
     try {
-      unlinkSync4(path4);
+      unlinkSync5(path5);
     } catch {
     }
     return take() !== "held";
@@ -3973,23 +4747,23 @@ var claimNotification = (sessionID, kind) => {
   }
 };
 var releaseNotificationClaim = (sessionID, kind) => {
-  const path4 = claimFile(sessionID, kind);
+  const path5 = claimFile(sessionID, kind);
   try {
-    const parsed = Number.parseInt(readFileSync7(path4, "utf8").trim(), 10);
+    const parsed = Number.parseInt(readFileSync9(path5, "utf8").trim(), 10);
     if (!Number.isFinite(parsed) || parsed <= 0) return;
     if (parsed !== process.pid) return;
-    unlinkSync4(path4);
+    unlinkSync5(path5);
   } catch {
   }
 };
-var completionFile = (sessionID) => join7(notificationStateDir(), `completion.${safeCorrelationKey(sessionID)}`);
+var completionFile = (sessionID) => join9(notificationStateDir(), `completion.${safeCorrelationKey(sessionID)}`);
 var claimCompletion = (sessionID, kind) => {
-  const path4 = completionFile(sessionID);
+  const path5 = completionFile(sessionID);
   try {
-    mkdirSync5(notificationStateDir(), { recursive: true });
-    const fd = openSync2(path4, "wx");
+    mkdirSync6(notificationStateDir(), { recursive: true });
+    const fd = openSync2(path5, "wx");
     try {
-      writeFileSync5(fd, `${process.pid} ${kind}
+      writeFileSync7(fd, `${process.pid} ${kind}
 `);
     } finally {
       closeSync2(fd);
@@ -4002,18 +4776,18 @@ var claimCompletion = (sessionID, kind) => {
 };
 var releaseCompletion = (sessionID) => {
   try {
-    unlinkSync4(completionFile(sessionID));
+    unlinkSync5(completionFile(sessionID));
   } catch {
   }
 };
 var markCompletion = (sessionID, kind) => {
   try {
-    mkdirSync5(notificationStateDir(), { recursive: true });
-    const path4 = completionFile(sessionID);
-    const tmp = `${path4}.${process.pid}.tmp`;
-    writeFileSync5(tmp, `${process.pid} ${kind}
+    mkdirSync6(notificationStateDir(), { recursive: true });
+    const path5 = completionFile(sessionID);
+    const tmp = `${path5}.${process.pid}.tmp`;
+    writeFileSync7(tmp, `${process.pid} ${kind}
 `);
-    renameSync4(tmp, path4);
+    renameSync5(tmp, path5);
   } catch {
   }
 };
@@ -4034,13 +4808,13 @@ var findHelper = () => {
   const home = process.env.HOME ?? "";
   const candidates = [
     process.env.OC_NOTIFY_HELPER,
-    path3.join(home, "bin", "lacode"),
-    path3.join(PACKAGE_ROOT, "dist", "lacode.js"),
-    path3.join(PACKAGE_ROOT, "bin", "lacode"),
-    path3.join(home, "bin", "oc-notify"),
-    path3.join(PACKAGE_ROOT, "bin", "oc-notify")
+    path4.join(home, "bin", "lacode"),
+    path4.join(PACKAGE_ROOT, "dist", "lacode.js"),
+    path4.join(PACKAGE_ROOT, "bin", "lacode"),
+    path4.join(home, "bin", "oc-notify"),
+    path4.join(PACKAGE_ROOT, "bin", "oc-notify")
   ].filter((candidate) => typeof candidate === "string" && candidate.length > 0);
-  for (const candidate of candidates) if (existsSync3(candidate)) return candidate;
+  for (const candidate of candidates) if (existsSync4(candidate)) return candidate;
   return void 0;
 };
 var notifyHooks = (async ({ client, directory }, options, deps = {}) => {
@@ -4050,6 +4824,7 @@ var notifyHooks = (async ({ client, directory }, options, deps = {}) => {
   const soundEnv = (process.env[SOUND_ENV] ?? "").trim().toLowerCase();
   const soundOn = !SOUND_OFF_VALUES.includes(soundEnv) && opts.sound !== false;
   const notifier = new Notifier(COOLDOWN_MS2);
+  const instanceId = randomUUID2();
   const active = /* @__PURE__ */ new Set();
   const titles = /* @__PURE__ */ new Map();
   const pending = /* @__PURE__ */ new Set();
@@ -4152,10 +4927,10 @@ var notifyHooks = (async ({ client, directory }, options, deps = {}) => {
     const info = await client.session.get({ path: { id: sessionID }, query: { directory } }).then((result) => result.data).catch(() => void 0);
     return info;
   };
-  const deliverViaHelper = (title, message, urgency, sound, requestID, sessionID) => new Promise((resolve3) => {
+  const deliverViaHelper = (title, message, urgency, sound, requestID, sessionID) => new Promise((resolve4) => {
     if (inflight >= maxInflight) {
       void log("warn", `notification dropped: ${inflight} helpers already in flight`, { title });
-      resolve3({ ok: false, detail: `too many notification helpers in flight (${inflight})` });
+      resolve4({ ok: false, detail: `too many notification helpers in flight (${inflight})` });
       return;
     }
     const helper = findHelper();
@@ -4164,7 +4939,7 @@ var notifyHooks = (async ({ client, directory }, options, deps = {}) => {
         warnedHelper = true;
         void log("warn", "no oc-notify helper found; run 'bin/oc-sync' to install one");
       }
-      resolve3({ ok: false, detail: "no oc-notify helper found" });
+      resolve4({ ok: false, detail: "no oc-notify helper found" });
       return;
     }
     const childEnv = { ...process.env, ...sessionID ? { [NOTIFY_SESSION_ENV]: sessionID } : {} };
@@ -4187,7 +4962,7 @@ var notifyHooks = (async ({ client, directory }, options, deps = {}) => {
       settled = true;
       inflight--;
       if (timer) clearTimeout(timer);
-      resolve3(result);
+      resolve4(result);
     };
     timer = setTimeout(() => {
       try {
@@ -4345,7 +5120,7 @@ var notifyHooks = (async ({ client, directory }, options, deps = {}) => {
           void log("debug", "suppressed: completion already announced", { sessionID });
           return;
         }
-      } else if (!claimNotification(sessionID, kind)) {
+      } else if (!claimNotification(sessionID, kind, instanceId)) {
         void log("debug", "suppressed: another process is raising this", { sessionID, kind });
         return;
       } else if (outcome === "error") {
@@ -4508,9 +5283,9 @@ function normalizeBaseURL(raw) {
     return null;
   }
   if (url.protocol !== "http:" && url.protocol !== "https:") return null;
-  let path4 = url.pathname.replace(/\/+$/, "");
-  while (path4.endsWith("/v1")) path4 = path4.slice(0, -"/v1".length);
-  return `${url.origin}${path4}/v1`;
+  let path5 = url.pathname.replace(/\/+$/, "");
+  while (path5.endsWith("/v1")) path5 = path5.slice(0, -"/v1".length);
+  return `${url.origin}${path5}/v1`;
 }
 function parseConfig(raw, env = process.env) {
   if (typeof raw !== "object" || raw === null) return { enabled: false, config: null, problems: [] };
@@ -5016,6 +5791,7 @@ var LaCode = (async (input, options) => {
   const autoupdate = await settled("context-autoupdate", () => contextAutoUpdateHooks(input, options)) ?? inertHooks;
   const notifier = await settled("notify", () => notifyHooks(input, options)) ?? inertHooks;
   const selfupdate = await settled("self-update", () => selfUpdateHooks(input, options)) ?? inertHooks;
+  const feedback = await settled("feedback", () => feedbackHooks(input, options)) ?? inertHooks;
   const omniroute = await settled("omniroute", () => omniRouteHooks(input, options)) ?? inertHooks;
   const imagepaste = await settled("image-paste", () => imagePasteHooks(input, opts.imagePaste)) ?? inertHooks;
   const config = async (cfg) => {
@@ -5058,6 +5834,7 @@ var LaCode = (async (input, options) => {
       await autoupdate.dispose?.();
       await notifier.dispose?.();
       await selfupdate.dispose?.();
+      await feedback.dispose?.();
       await omniroute.dispose?.();
       await imagepaste.dispose?.();
     },