@mnemonik/shared 6.17.0 → 6.18.0

package/dist/usageGuide.d.ts

@@ -4,12 +4,12 @@
  * This is the SINGLE SOURCE OF TRUTH for the usage guide.
  * Shared usage guide content imported by the server.
  *
- * Version: 2.83
- * Updated: 2026-07-17 - Doc-drift-throughput: teach bounded document packets,
- *          current locators, and independently evidenced verdict batches.
+ * Version: 2.84
+ * Updated: 2026-07-17 - Doc-drift continuous disposition: every finding ends
+ *          in an edit, evidenced verdict, or needs-review route.
  *
  * This guide focuses on HOW to use Mnemonik effectively, not WHAT tools exist.
  * Tool schemas already tell agents what's available - they need the workflow.
  */
-export declare const USAGE_GUIDE = "# Mnemonik Workflow Guide (v2.83)\n\n## Workflow\n\nsession_bootstrap \u2192 memory_search \u2192 file_context \u2192 [work] \u2192 memory_add \u2192 memory_state\n\n## Tool Selection by Stage\n\n### Session start\n- session_bootstrap: loads context, policies, pending tasks (call once, first thing)\n- memory_search: search by task domain; set workflowContext (feature_implementation, debugging, exploration, policy_review)\n- projects: resolve project IDs if context unclear\n- policy: review safety rules\n\n### Before editing files\n- file_context: fetch memories for the file \u2014 call for EVERY file you edit\n- memory_search: second search scoped to file/module if needed\n- mnemonik.docs({ action: 'links' }): check doc couplings for the file\n\n### During implementation\n- memory_get: retrieve specific memory by id\n- memory_update: refine memory created this session\n- memory_info: query history, provenance, confidence breakdown, links, graph\n- assist: get tool guidance if uncertain\n\n### Documentation drift\n- Drift is drift: every finding returned by mnemonik.docs({ action: 'drift' }) is normal development work, including prose that requires agent reasoning. Queue size is never a reason to defer or dismiss it.\n- Start with mnemonik.docs({ action: 'drift', summaryOnly: true }) for the document inventory, choose a document, then use its exact retrieve call for a bounded work packet.\n- Each packet resolves the current Markdown heading range and current code locations from stable heading/symbol/snippet identities. Use those current locations; line numbers are display metadata and may move.\n- Fix update_doc/regenerate_doc findings in the document. For verify_and_report findings, inspect the cited code and submit mnemonik.docs({ action: 'verdicts', items: [...] }) with an independent cited evidence string for every item.\n- Follow each document's retrieveMore call and the inventory cursor until complete. Do not sample, suppress, or down-rank obligations because the queue is large.\n\n### After significant work\n- memory_add: save decisions, outcomes, patterns, bug root causes\n- memory_state: reinforce (memory helped), supersede (replace outdated), deprecate, penalize, dispute\n- tasks: mark tasks in progress or complete\n- mnemonik.docs({ action: 'status' }): view doc-truth health (legacy coupling counts are diagnostic only \u2014 do not act on them as drift)\n\n### Diagnostics\n- doctor: when tool calls fail or behavior is inconsistent\n- scanner: refresh embeddings, trigger scans, check drift\n\n## Skip conditions\n\nSkip memory tools for: formatting-only edits, trivial one-line changes, mechanical refactors, git operations, running tests.\n\n## Completion gate\n\nNever tell the user significant work is done without calling memory_add first in the same response. Changes made + responding next = completion. \"Progress updates\" count.\n\n## Memory search tips\n\n- Query should include task intent + key entities\n- Set workflowContext when you know the phase\n- Use currentFile to boost file-linked memories\n- Use filterOnly:true only for narrow filters (no embedding, requires >=1 filter)\n\n## Proactive heuristics\n\n- Long sessions: re-run memory_search after switching topics\n- Conflicting info: use memory_state to supersede/dispute\n- High-impact changes: save memory immediately after verification\n- Act on every docTruthFindings/_docDrift obligation: edit update_doc/regenerate_doc findings and reason through verify_and_report prose findings. linkedDocs and stale-coupling counts alone remain legacy diagnostics\n\n## Anti-fade (every ~10 tool calls)\n\nCheck: (1) memory_search before work? (2) file_context before edit? (3) memory_add after completing? No session_bootstrap? Call it now.\n";
+export declare const USAGE_GUIDE = "# Mnemonik Workflow Guide (v2.84)\n\n## Workflow\n\nsession_bootstrap \u2192 memory_search \u2192 file_context \u2192 [work] \u2192 memory_add \u2192 memory_state\n\n## Tool Selection by Stage\n\n### Session start\n- session_bootstrap: loads context, policies, pending tasks (call once, first thing)\n- memory_search: search by task domain; set workflowContext (feature_implementation, debugging, exploration, policy_review)\n- projects: resolve project IDs if context unclear\n- policy: review safety rules\n\n### Before editing files\n- file_context: fetch memories for the file \u2014 call for EVERY file you edit\n- memory_search: second search scoped to file/module if needed\n- mnemonik.docs({ action: 'links' }): check doc couplings for the file\n\n### During implementation\n- memory_get: retrieve specific memory by id\n- memory_update: refine memory created this session\n- memory_info: query history, provenance, confidence breakdown, links, graph\n- assist: get tool guidance if uncertain\n\n### Documentation drift\n- Drift is drift: every finding returned by mnemonik.docs({ action: 'drift' }) is normal development work, including prose that requires agent reasoning. Queue size is never a reason to defer or dismiss it.\n- Start with mnemonik.docs({ action: 'drift', summaryOnly: true }) for the document inventory, choose a document, then use its exact retrieve call for a bounded work packet.\n- Each packet resolves the current Markdown heading range and current code locations from stable heading/symbol/snippet identities. Use those current locations; line numbers are display metadata and may move.\n- Work every finding in packet order. Prose versus code is not a scope distinction; it only changes which project evidence is relevant.\n- Fix update_doc/regenerate_doc findings in the document. For settled verify_and_report findings, submit mnemonik.docs({ action: 'verdicts', items: [...] }) with an independent cited evidence string for every item. If available evidence cannot settle a claim, call mnemonik.docs({ action: 'flag_for_review', findingId, evidence }) and continue.\n- Absence of repository evidence is not refutation. Claims about human intent, plans, positioning, or external facts require affirmative contradictory evidence to refute; otherwise flag them for review and continue.\n- Follow each document's retrieveMore call and the inventory cursor until complete. remainingFindings > 0 also means the task is not complete: continue immediately. Do not sample the queue, design a separate execution strategy, ask the user to triage routine uncertainty, suppress, or down-rank obligations because the queue is large.\n\n### After significant work\n- memory_add: save decisions, outcomes, patterns, bug root causes\n- memory_state: reinforce (memory helped), supersede (replace outdated), deprecate, penalize, dispute\n- tasks: mark tasks in progress or complete\n- mnemonik.docs({ action: 'status' }): view doc-truth health (legacy coupling counts are diagnostic only \u2014 do not act on them as drift)\n\n### Diagnostics\n- doctor: when tool calls fail or behavior is inconsistent\n- scanner: refresh embeddings, trigger scans, check drift\n\n## Skip conditions\n\nSkip memory tools for: formatting-only edits, trivial one-line changes, mechanical refactors, git operations, running tests.\n\n## Completion gate\n\nNever tell the user significant work is done without calling memory_add first in the same response. Changes made + responding next = completion. \"Progress updates\" count.\n\n## Memory search tips\n\n- Query should include task intent + key entities\n- Set workflowContext when you know the phase\n- Use currentFile to boost file-linked memories\n- Use filterOnly:true only for narrow filters (no embedding, requires >=1 filter)\n\n## Proactive heuristics\n\n- Long sessions: re-run memory_search after switching topics\n- Conflicting info: use memory_state to supersede/dispute\n- High-impact changes: save memory immediately after verification\n- Act on every docTruthFindings/_docDrift obligation: edit update_doc/regenerate_doc findings, submit supported verify_and_report verdicts, or flag an evidenced uncertainty for review and continue. linkedDocs and stale-coupling counts alone remain legacy diagnostics\n\n## Anti-fade (every ~10 tool calls)\n\nCheck: (1) memory_search before work? (2) file_context before edit? (3) memory_add after completing? No session_bootstrap? Call it now.\n";
 //# sourceMappingURL=usageGuide.d.ts.map

package/dist/usageGuide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usageGuide.d.ts","sourceRoot":"","sources":["../src/usageGuide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,WAAW,urHAmEvB,CAAC"}
+{"version":3,"file":"usageGuide.d.ts","sourceRoot":"","sources":["../src/usageGuide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,WAAW,w2IAqEvB,CAAC"}

package/dist/usageGuide.js

@@ -4,14 +4,14 @@
  * This is the SINGLE SOURCE OF TRUTH for the usage guide.
  * Shared usage guide content imported by the server.
  *
- * Version: 2.83
- * Updated: 2026-07-17 - Doc-drift-throughput: teach bounded document packets,
- *          current locators, and independently evidenced verdict batches.
+ * Version: 2.84
+ * Updated: 2026-07-17 - Doc-drift continuous disposition: every finding ends
+ *          in an edit, evidenced verdict, or needs-review route.
  *
  * This guide focuses on HOW to use Mnemonik effectively, not WHAT tools exist.
  * Tool schemas already tell agents what's available - they need the workflow.
  */
-export const USAGE_GUIDE = `# Mnemonik Workflow Guide (v2.83)
+export const USAGE_GUIDE = `# Mnemonik Workflow Guide (v2.84)
 
 ## Workflow
 
@@ -40,8 +40,10 @@ session_bootstrap → memory_search → file_context → [work] → memory_add
 - Drift is drift: every finding returned by mnemonik.docs({ action: 'drift' }) is normal development work, including prose that requires agent reasoning. Queue size is never a reason to defer or dismiss it.
 - Start with mnemonik.docs({ action: 'drift', summaryOnly: true }) for the document inventory, choose a document, then use its exact retrieve call for a bounded work packet.
 - Each packet resolves the current Markdown heading range and current code locations from stable heading/symbol/snippet identities. Use those current locations; line numbers are display metadata and may move.
-- Fix update_doc/regenerate_doc findings in the document. For verify_and_report findings, inspect the cited code and submit mnemonik.docs({ action: 'verdicts', items: [...] }) with an independent cited evidence string for every item.
-- Follow each document's retrieveMore call and the inventory cursor until complete. Do not sample, suppress, or down-rank obligations because the queue is large.
+- Work every finding in packet order. Prose versus code is not a scope distinction; it only changes which project evidence is relevant.
+- Fix update_doc/regenerate_doc findings in the document. For settled verify_and_report findings, submit mnemonik.docs({ action: 'verdicts', items: [...] }) with an independent cited evidence string for every item. If available evidence cannot settle a claim, call mnemonik.docs({ action: 'flag_for_review', findingId, evidence }) and continue.
+- Absence of repository evidence is not refutation. Claims about human intent, plans, positioning, or external facts require affirmative contradictory evidence to refute; otherwise flag them for review and continue.
+- Follow each document's retrieveMore call and the inventory cursor until complete. remainingFindings > 0 also means the task is not complete: continue immediately. Do not sample the queue, design a separate execution strategy, ask the user to triage routine uncertainty, suppress, or down-rank obligations because the queue is large.
 
 ### After significant work
 - memory_add: save decisions, outcomes, patterns, bug root causes
@@ -73,7 +75,7 @@ Never tell the user significant work is done without calling memory_add first in
 - Long sessions: re-run memory_search after switching topics
 - Conflicting info: use memory_state to supersede/dispute
 - High-impact changes: save memory immediately after verification
-- Act on every docTruthFindings/_docDrift obligation: edit update_doc/regenerate_doc findings and reason through verify_and_report prose findings. linkedDocs and stale-coupling counts alone remain legacy diagnostics
+- Act on every docTruthFindings/_docDrift obligation: edit update_doc/regenerate_doc findings, submit supported verify_and_report verdicts, or flag an evidenced uncertainty for review and continue. linkedDocs and stale-coupling counts alone remain legacy diagnostics
 
 ## Anti-fade (every ~10 tool calls)
 

package/dist/usageGuide.js.map

@@ -1 +1 @@
-{"version":3,"file":"usageGuide.js","sourceRoot":"","sources":["../src/usageGuide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmE1B,CAAC"}
+{"version":3,"file":"usageGuide.js","sourceRoot":"","sources":["../src/usageGuide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqE1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemonik/shared",
-  "version": "6.17.0",
+  "version": "6.18.0",
   "description": "Shared constants and utilities for Mnemonik packages",
   "type": "module",
   "main": "dist/index.js",

package/src/usageGuide.ts

@@ -4,15 +4,15 @@
  * This is the SINGLE SOURCE OF TRUTH for the usage guide.
  * Shared usage guide content imported by the server.
  *
- * Version: 2.83
- * Updated: 2026-07-17 - Doc-drift-throughput: teach bounded document packets,
- *          current locators, and independently evidenced verdict batches.
+ * Version: 2.84
+ * Updated: 2026-07-17 - Doc-drift continuous disposition: every finding ends
+ *          in an edit, evidenced verdict, or needs-review route.
  *
  * This guide focuses on HOW to use Mnemonik effectively, not WHAT tools exist.
  * Tool schemas already tell agents what's available - they need the workflow.
  */
 
-export const USAGE_GUIDE = `# Mnemonik Workflow Guide (v2.83)
+export const USAGE_GUIDE = `# Mnemonik Workflow Guide (v2.84)
 
 ## Workflow
 
@@ -41,8 +41,10 @@ session_bootstrap → memory_search → file_context → [work] → memory_add
 - Drift is drift: every finding returned by mnemonik.docs({ action: 'drift' }) is normal development work, including prose that requires agent reasoning. Queue size is never a reason to defer or dismiss it.
 - Start with mnemonik.docs({ action: 'drift', summaryOnly: true }) for the document inventory, choose a document, then use its exact retrieve call for a bounded work packet.
 - Each packet resolves the current Markdown heading range and current code locations from stable heading/symbol/snippet identities. Use those current locations; line numbers are display metadata and may move.
-- Fix update_doc/regenerate_doc findings in the document. For verify_and_report findings, inspect the cited code and submit mnemonik.docs({ action: 'verdicts', items: [...] }) with an independent cited evidence string for every item.
-- Follow each document's retrieveMore call and the inventory cursor until complete. Do not sample, suppress, or down-rank obligations because the queue is large.
+- Work every finding in packet order. Prose versus code is not a scope distinction; it only changes which project evidence is relevant.
+- Fix update_doc/regenerate_doc findings in the document. For settled verify_and_report findings, submit mnemonik.docs({ action: 'verdicts', items: [...] }) with an independent cited evidence string for every item. If available evidence cannot settle a claim, call mnemonik.docs({ action: 'flag_for_review', findingId, evidence }) and continue.
+- Absence of repository evidence is not refutation. Claims about human intent, plans, positioning, or external facts require affirmative contradictory evidence to refute; otherwise flag them for review and continue.
+- Follow each document's retrieveMore call and the inventory cursor until complete. remainingFindings > 0 also means the task is not complete: continue immediately. Do not sample the queue, design a separate execution strategy, ask the user to triage routine uncertainty, suppress, or down-rank obligations because the queue is large.
 
 ### After significant work
 - memory_add: save decisions, outcomes, patterns, bug root causes
@@ -74,7 +76,7 @@ Never tell the user significant work is done without calling memory_add first in
 - Long sessions: re-run memory_search after switching topics
 - Conflicting info: use memory_state to supersede/dispute
 - High-impact changes: save memory immediately after verification
-- Act on every docTruthFindings/_docDrift obligation: edit update_doc/regenerate_doc findings and reason through verify_and_report prose findings. linkedDocs and stale-coupling counts alone remain legacy diagnostics
+- Act on every docTruthFindings/_docDrift obligation: edit update_doc/regenerate_doc findings, submit supported verify_and_report verdicts, or flag an evidenced uncertainty for review and continue. linkedDocs and stale-coupling counts alone remain legacy diagnostics
 
 ## Anti-fade (every ~10 tool calls)