@mnemonik/shared 6.19.0 → 6.20.1

package/dist/usageGuide.d.ts

@@ -4,12 +4,11 @@
  * This is the SINGLE SOURCE OF TRUTH for the usage guide.
  * Shared usage guide content imported by the server.
  *
- * Version: 2.84
- * Updated: 2026-07-17 - Doc-drift continuous disposition: every finding ends
- *          in an edit, evidenced verdict, or needs-review route.
+ * Version: 2.85
+ * Updated: 2026-07-18 - Change-scoped, document-parallel doc-drift workflow.
  *
  * 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.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";
+export declare const USAGE_GUIDE = "# Mnemonik Workflow Guide (v2.85)\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- An unscoped mnemonik.docs({ action: 'drift' }) call defaults to the schema-v3 affected-document inventory; a scoped call defaults to its detailed packet. Each document is an independent work unit. Recommended default: delegate each affected document to a subagent and start available document workers together; pass docPath and the compact retrieve call instead of copying finding bodies. This is advisory orchestration, not a host-enforced ownership rule.\n- Detailed retrieval defaults to one document and returns at most 8 findings within 16 KiB. Each packet carries compact causal triggers plus current Markdown and code locations resolved from stable identities; line numbers are display metadata and may move.\n- Complete every finding in the document: edit update_doc/regenerate_doc items, submit mnemonik.docs({ action: 'verdicts', scopePath, items: [...] }) with independently cited evidence for settled verify_and_report items, or call mnemonik.docs({ action: 'flag_for_review', scopePath, findingId, evidence }) when inspected evidence cannot settle a claim.\n- The document under review cannot confirm or refute its own claim. Verdict evidence must cite an independent source; route a rejected circular verdict to flag_for_review.\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.\n- Follow the document-local retrieveMore call until that document is complete, and follow inventory cursors until every affected document has a terminal disposition.\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- Treat each affected document in docTruthFindings/_docDrift as an independent work unit. Complete its scoped packet with edits, supported verdicts, or an evidenced review disposition. 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,w2IAqEvB,CAAC"}
+{"version":3,"file":"usageGuide.d.ts","sourceRoot":"","sources":["../src/usageGuide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,WAAW,+0IAoEvB,CAAC"}

package/dist/usageGuide.js

@@ -4,14 +4,13 @@
  * This is the SINGLE SOURCE OF TRUTH for the usage guide.
  * Shared usage guide content imported by the server.
  *
- * Version: 2.84
- * Updated: 2026-07-17 - Doc-drift continuous disposition: every finding ends
- *          in an edit, evidenced verdict, or needs-review route.
+ * Version: 2.85
+ * Updated: 2026-07-18 - Change-scoped, document-parallel doc-drift workflow.
  *
  * 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.84)
+export const USAGE_GUIDE = `# Mnemonik Workflow Guide (v2.85)
 
 ## Workflow
 
@@ -37,13 +36,12 @@ session_bootstrap → memory_search → file_context → [work] → memory_add
 - assist: get tool guidance if uncertain
 
 ### Documentation drift
-- 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.
-- 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.
+- An unscoped mnemonik.docs({ action: 'drift' }) call defaults to the schema-v3 affected-document inventory; a scoped call defaults to its detailed packet. Each document is an independent work unit. Recommended default: delegate each affected document to a subagent and start available document workers together; pass docPath and the compact retrieve call instead of copying finding bodies. This is advisory orchestration, not a host-enforced ownership rule.
+- Detailed retrieval defaults to one document and returns at most 8 findings within 16 KiB. Each packet carries compact causal triggers plus current Markdown and code locations resolved from stable identities; line numbers are display metadata and may move.
+- Complete every finding in the document: edit update_doc/regenerate_doc items, submit mnemonik.docs({ action: 'verdicts', scopePath, items: [...] }) with independently cited evidence for settled verify_and_report items, or call mnemonik.docs({ action: 'flag_for_review', scopePath, findingId, evidence }) when inspected evidence cannot settle a claim.
+- The document under review cannot confirm or refute its own claim. Verdict evidence must cite an independent source; route a rejected circular verdict to flag_for_review.
+- 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.
+- Follow the document-local retrieveMore call until that document is complete, and follow inventory cursors until every affected document has a terminal disposition.
 
 ### After significant work
 - memory_add: save decisions, outcomes, patterns, bug root causes
@@ -75,7 +73,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, submit supported verify_and_report verdicts, or flag an evidenced uncertainty for review and continue. linkedDocs and stale-coupling counts alone remain legacy diagnostics
+- Treat each affected document in docTruthFindings/_docDrift as an independent work unit. Complete its scoped packet with edits, supported verdicts, or an evidenced review disposition. 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqE1B,CAAC"}
+{"version":3,"file":"usageGuide.js","sourceRoot":"","sources":["../src/usageGuide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoE1B,CAAC"}

package/package.json

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

package/src/usageGuide.ts

@@ -4,15 +4,14 @@
  * This is the SINGLE SOURCE OF TRUTH for the usage guide.
  * Shared usage guide content imported by the server.
  *
- * Version: 2.84
- * Updated: 2026-07-17 - Doc-drift continuous disposition: every finding ends
- *          in an edit, evidenced verdict, or needs-review route.
+ * Version: 2.85
+ * Updated: 2026-07-18 - Change-scoped, document-parallel doc-drift workflow.
  *
  * 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.84)
+export const USAGE_GUIDE = `# Mnemonik Workflow Guide (v2.85)
 
 ## Workflow
 
@@ -38,13 +37,12 @@ session_bootstrap → memory_search → file_context → [work] → memory_add
 - assist: get tool guidance if uncertain
 
 ### Documentation drift
-- 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.
-- 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.
+- An unscoped mnemonik.docs({ action: 'drift' }) call defaults to the schema-v3 affected-document inventory; a scoped call defaults to its detailed packet. Each document is an independent work unit. Recommended default: delegate each affected document to a subagent and start available document workers together; pass docPath and the compact retrieve call instead of copying finding bodies. This is advisory orchestration, not a host-enforced ownership rule.
+- Detailed retrieval defaults to one document and returns at most 8 findings within 16 KiB. Each packet carries compact causal triggers plus current Markdown and code locations resolved from stable identities; line numbers are display metadata and may move.
+- Complete every finding in the document: edit update_doc/regenerate_doc items, submit mnemonik.docs({ action: 'verdicts', scopePath, items: [...] }) with independently cited evidence for settled verify_and_report items, or call mnemonik.docs({ action: 'flag_for_review', scopePath, findingId, evidence }) when inspected evidence cannot settle a claim.
+- The document under review cannot confirm or refute its own claim. Verdict evidence must cite an independent source; route a rejected circular verdict to flag_for_review.
+- 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.
+- Follow the document-local retrieveMore call until that document is complete, and follow inventory cursors until every affected document has a terminal disposition.
 
 ### After significant work
 - memory_add: save decisions, outcomes, patterns, bug root causes
@@ -76,7 +74,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, submit supported verify_and_report verdicts, or flag an evidenced uncertainty for review and continue. linkedDocs and stale-coupling counts alone remain legacy diagnostics
+- Treat each affected document in docTruthFindings/_docDrift as an independent work unit. Complete its scoped packet with edits, supported verdicts, or an evidenced review disposition. linkedDocs and stale-coupling counts alone remain legacy diagnostics
 
 ## Anti-fade (every ~10 tool calls)