@tomingtoming/kioq 0.8.2 → 0.9.0

package/dist/src/engagement.js

@@ -0,0 +1,130 @@
+const HUMAN_SIGNALS = new Set([
+    "human_cited",
+    "human_discussed",
+    "human_applied",
+    "human_questioned",
+    "human_dismissed",
+]);
+const SIGNAL_STRENGTH = {
+    search_hit: 1,
+    context_pulled: 2,
+    read: 3,
+    orient_discovered: 4,
+    orient_referenced: 5,
+    modified: 6,
+    human_questioned: 7,
+    human_cited: 8,
+    human_discussed: 9,
+    human_dismissed: 5,
+    human_applied: 10,
+};
+export class EngagementIndex {
+    facetsMap = new Map();
+    build(signals, notes) {
+        this.facetsMap.clear();
+        const notesByPermalink = new Map();
+        for (const note of notes) {
+            notesByPermalink.set(note.permalink, note);
+        }
+        // Initialize facets for all notes
+        for (const note of notes) {
+            this.facetsMap.set(note.permalink, this.emptyFacets(note.frontmatter));
+        }
+        // Process signal log
+        for (const signal of signals) {
+            const facets = this.facetsMap.get(signal.note);
+            if (!facets)
+                continue;
+            facets.contactCount++;
+            if (!facets.lastContact || signal.ts > facets.lastContact) {
+                facets.lastContact = signal.ts;
+            }
+            if (HUMAN_SIGNALS.has(signal.op)) {
+                facets.humanSignalCount++;
+                if (!facets.lastHumanSignal || signal.ts > facets.lastHumanSignal) {
+                    facets.lastHumanSignal = signal.ts;
+                }
+            }
+            if (!facets.dominantSignal || SIGNAL_STRENGTH[signal.op] > SIGNAL_STRENGTH[facets.dominantSignal]) {
+                facets.dominantSignal = signal.op;
+            }
+        }
+        // Compute ai_reference_count and synthesis_count from note content
+        const wikiLinkPattern = /\[\[([^\]\n]+)\]\]/g;
+        for (const note of notes) {
+            const origin = safeString(note.frontmatter.origin);
+            if (origin !== "ai" && origin !== "collaborative")
+                continue;
+            const links = new Set();
+            let match;
+            while ((match = wikiLinkPattern.exec(note.body)) !== null) {
+                const target = match[1].split("|")[0].trim();
+                links.add(target);
+            }
+            wikiLinkPattern.lastIndex = 0;
+            for (const target of links) {
+                // Try to resolve the target to a permalink
+                const resolved = this.resolveTarget(target, notes, notesByPermalink);
+                if (resolved) {
+                    const targetFacets = this.facetsMap.get(resolved);
+                    if (targetFacets) {
+                        targetFacets.aiReferenceCount++;
+                    }
+                }
+            }
+            // Check if this note is a synthesis (has parent or source links)
+            const parentMatch = /^-\s*(?:親|parent):\s*\[\[([^\]]+)\]\]/im.exec(note.body);
+            if (parentMatch && (origin === "ai" || origin === "collaborative")) {
+                const parentTarget = parentMatch[1].split("|")[0].trim();
+                const resolved = this.resolveTarget(parentTarget, notes, notesByPermalink);
+                if (resolved) {
+                    const parentFacets = this.facetsMap.get(resolved);
+                    if (parentFacets) {
+                        parentFacets.synthesisCount++;
+                    }
+                }
+            }
+        }
+    }
+    get(permalink) {
+        return this.facetsMap.get(permalink);
+    }
+    getAll() {
+        return this.facetsMap;
+    }
+    resolveTarget(target, notes, byPermalink) {
+        // Direct permalink match
+        if (byPermalink.has(target))
+            return target;
+        // Title match (case-insensitive)
+        const lowerTarget = target.toLowerCase();
+        for (const note of notes) {
+            if (note.title.toLowerCase() === lowerTarget)
+                return note.permalink;
+            if (note.permalink.toLowerCase() === lowerTarget)
+                return note.permalink;
+            const basename = note.permalink.split("/").pop()?.toLowerCase();
+            if (basename === lowerTarget)
+                return note.permalink;
+        }
+        return undefined;
+    }
+    emptyFacets(frontmatter) {
+        return {
+            contactCount: 0,
+            lastContact: null,
+            humanSignalCount: 0,
+            lastHumanSignal: null,
+            dominantSignal: null,
+            aiReferenceCount: 0,
+            synthesisCount: 0,
+            origin: safeString(frontmatter.origin),
+            createdVia: safeString(frontmatter.created_via),
+        };
+    }
+}
+function safeString(value) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    return null;
+}

package/dist/src/index.js

@@ -3,13 +3,14 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { lintStructureResponseModeHint, lintStructureResponsePlan, summarizeLintStructureResponse, } from "./auditResponseSummary.js";
 import { loadConfig } from "./config.js";
-import { memoryContractResponseModeHint, memoryContractResponsePlan, summarizeMemoryContractResponse, } from "./contractResponseSummary.js";
 import { summarizeNoConflict } from "./conflictSummary.js";
 import { LocalNoteStore } from "./noteStore.js";
 import { GitHubStorage, LocalFsStorage } from "./storage/index.js";
+import { SignalLog } from "./signalLog.js";
+import { EngagementIndex } from "./engagement.js";
 import { normalizeDateInput, preview } from "./normalizers.js";
 import { summarizeDeleteImpact, summarizeRenameImpact } from "./operationImpact.js";
-import { summarizeBacklinksResponse, summarizeContextBundleResponse, summarizeReadNoteResponse, summarizeRecentResponse, summarizeResolveLinksResponse, summarizeSearchResponse, } from "./readResponseSummary.js";
+import { summarizeReadNoteResponse, summarizeSearchResponse, } from "./readResponseSummary.js";
 import { summarizeLintChangeTrigger, summarizeReadChangeTrigger } from "./changeTriggerSummary.js";
 import { RESPONSE_MODE_VALUES, normalizeResponseMode, responseModeAtLeast } from "./responseMode.js";
 import { TOOL_SCOPE_LABELS, responsibilityWarningCode } from "./toolScope.js";
@@ -288,6 +289,8 @@ async function main() {
         : new LocalFsStorage(config.root);
     await storage.ensureRoot();
     const store = new LocalNoteStore(config, storage);
+    const signalLog = new SignalLog(storage);
+    const engagementIndex = new EngagementIndex();
     const appendStorageContext = (lines) => {
         lines.push(`storage_backend: ${config.github ? "github" : "filesystem"}`);
         lines.push(`storage_root: ${config.root}`);
@@ -312,56 +315,65 @@ async function main() {
         name: "kioq",
         version: "0.7.0",
     });
-    server.tool("recent_notes", "最近更新したノートを一覧します。", {
-        limit: z.number().int().min(1).max(50).optional().describe("最大件数 (default: 10)"),
-        directory: z.string().min(1).optional().describe("指定時は配下ディレクトリに限定"),
-        response_mode: responseModeSchema,
-    }, async ({ limit, directory, response_mode }) => {
-        const responseMode = normalizeResponseMode(response_mode);
-        const result = await store.recentNotes({
-            limit: limit ?? 10,
-            directory,
-        });
-        const firstIndexLike = result.results.find((item) => item.indexLike);
-        const summary = summarizeRecentResponse({
-            resultCount: result.results.length,
-            firstResultTitle: result.results[0]?.title,
-            hasIndexLikeResult: Boolean(firstIndexLike),
-            firstIndexLikeTitle: firstIndexLike?.title,
-            indexCandidateCount: result.indexNoteCandidates.length,
-            firstIndexCandidateTitle: result.indexNoteCandidates[0]?.title,
+    server.tool("orient", "kioqを通じて思考を構造化するツール。チェインバー型パイロット支援システムとして、応答を組み立てる前に現在の思考を渡すことで、3つのスロットを返します: (1) relevant — 思考に直接関連するノート（engagement重み付け）、(2) active_context — 進行中のflowと最近のアクティブなノート、(3) discovery — 未接触だが接点がありそうなノート（セレンディピティ）。各ノートのengagement（接触回数、人間の反応、AI被参照数、origin）が付与されます。observationで人間の反応を記録でき、それがengagementに蓄積されます。対話の各ターンで呼び出すことを推奨します。", {
+        thought: z.string().min(1).describe("今何を考えているか、何について応答しようとしているか"),
+        references: z.array(z.string()).optional().describe("明示的に関連するノートの identifier（あれば）"),
+        observation: z.object({
+            note: z.string().min(1).describe("観察対象のノート identifier"),
+            signal: z.enum(["cited", "discussed", "applied", "questioned", "dismissed"]).describe("人間の反応の種類"),
+        }).optional().describe("直前の対話で人間がノートの概念に反応した場合に記録"),
+    }, async ({ thought, references, observation }) => {
+        const signals = await signalLog.load();
+        const notes = await store.loadAllNotes();
+        engagementIndex.build(signals, notes);
+        const result = await store.orient({
+            thought,
+            references,
+            observation,
+            engagementIndex,
+            signalLog,
         });
+        await signalLog.flush();
         const lines = [];
-        lines.push(`対象プロジェクト: ${result.project}`);
+        lines.push(`project: ${result.project}`);
         appendStorageContext(lines);
-        appendScopeLabel(lines, TOOL_SCOPE_LABELS.recent_notes);
-        lines.push(`response_mode: ${responseMode}`);
-        appendReadResponseSummary(lines, summary);
-        lines.push(`件数: ${result.results.length}`);
+        lines.push(`scope_label: orient`);
+        lines.push(`thought: ${thought.slice(0, 200)}`);
         lines.push("");
-        if (result.results.length === 0) {
-            lines.push("候補が見つかりませんでした。");
+        if (result.relevant.length > 0) {
+            lines.push("--- relevant ---");
+            for (const item of result.relevant) {
+                lines.push(`- ${item.title}`);
+                lines.push(`  permalink: ${item.permalink}`);
+                lines.push(`  reason: ${item.reason}`);
+                lines.push(`  engagement: contact=${item.engagement.contactCount} human=${item.engagement.humanSignalCount} ai_ref=${item.engagement.aiReferenceCount} origin=${item.engagement.origin ?? "unknown"} created_via=${item.engagement.createdVia ?? "unknown"}`);
+                lines.push(`  snippet: ${item.snippet.slice(0, 200)}`);
+            }
+            lines.push("");
         }
-        else {
-            result.results.forEach((item, index) => {
-                lines.push(`${index + 1}. ${item.title}`);
-                lines.push(`   updated: ${item.updated}`);
-                if (responseModeAtLeast(responseMode, "standard")) {
-                    lines.push(`   permalink: ${item.permalink}`);
-                    lines.push(`   file: ${item.filePath}`);
-                    lines.push(`   index_like: ${item.indexLike ? "yes" : "no"}`);
-                }
-                if (responseModeAtLeast(responseMode, "verbose")) {
-                    lines.push(`   index_like_reasons: ${item.indexLike && item.indexReasons.length > 0 ? item.indexReasons.join(", ") : "(none)"}`);
-                }
-            });
+        if (result.activeContext.length > 0) {
+            lines.push("--- active_context ---");
+            for (const item of result.activeContext) {
+                lines.push(`- ${item.title}`);
+                lines.push(`  permalink: ${item.permalink}`);
+                lines.push(`  reason: ${item.reason}`);
+                lines.push(`  engagement: contact=${item.engagement.contactCount} human=${item.engagement.humanSignalCount} origin=${item.engagement.origin ?? "unknown"}`);
+            }
+            lines.push("");
         }
-        if (responseModeAtLeast(responseMode, "verbose")) {
+        if (result.discovery.length > 0) {
+            lines.push("--- discovery ---");
+            for (const item of result.discovery) {
+                lines.push(`- ${item.title}`);
+                lines.push(`  permalink: ${item.permalink}`);
+                lines.push(`  reason: ${item.reason}`);
+                lines.push(`  engagement: contact=${item.engagement.contactCount} origin=${item.engagement.origin ?? "unknown"} created_via=${item.engagement.createdVia ?? "unknown"}`);
+                lines.push(`  snippet: ${item.snippet.slice(0, 160)}`);
+            }
             lines.push("");
-            appendIndexNoteCandidates(lines, result.indexNoteCandidates, "recommended_indexes");
         }
-        if (responseModeAtLeast(responseMode, "verbose")) {
-            await appendAutoProjectHealth(lines);
+        if (result.relevant.length === 0 && result.discovery.length === 0) {
+            lines.push("関連するノートは見つかりませんでした。");
         }
         return textResult(lines.join("\n"));
     });
@@ -522,279 +534,7 @@ async function main() {
             return textResult(lines.join("\n"));
         }
     });
-    server.tool("resolve_links", "ノート内の WikiLink を解決し、リンク先の存在状況を返します。", {
-        identifier: z.string().min(1),
-        response_mode: responseModeSchema,
-    }, async ({ identifier, response_mode }) => {
-        const responseMode = normalizeResponseMode(response_mode);
-        const result = await store.resolveLinks({
-            identifier,
-        });
-        const unresolvedLinkCount = result.links.filter((link) => !link.resolved).length;
-        const summary = summarizeResolveLinksResponse({
-            indexLike: result.indexLike,
-            unresolvedLinkCount,
-            boundaryWarningCount: result.boundaryWarnings.length,
-            indexCandidateTitle: result.indexNoteCandidates[0]?.title,
-        });
-        const lines = [];
-        lines.push(`identifier: ${identifier}`);
-        lines.push(`project: ${result.project}`);
-        appendStorageContext(lines);
-        appendScopeLabel(lines, TOOL_SCOPE_LABELS.resolve_links);
-        lines.push(`response_mode: ${responseMode}`);
-        appendReadResponseSummary(lines, summary);
-        appendResponsibilityWarning(lines, result.boundaryWarnings);
-        lines.push(`file: ${result.note.relativePath}`);
-        lines.push(`wikilinks: ${result.links.length}`);
-        if (responseModeAtLeast(responseMode, "verbose")) {
-            appendIndexLike(lines, result.indexLike, result.indexReasons);
-        }
-        appendBoundaryWarnings(lines, result.boundaryWarnings);
-        lines.push("");
-        if (result.links.length === 0) {
-            lines.push("WikiLink は見つかりませんでした。");
-        }
-        else {
-            result.links.forEach((link, index) => {
-                lines.push(`${index + 1}. ${link.raw}`);
-                if (link.resolved) {
-                    lines.push(`   resolved: yes`);
-                    lines.push(`   to: ${link.resolvedTitle} (${link.resolvedFilePath})`);
-                }
-                else {
-                    lines.push(`   resolved: no`);
-                    lines.push(`   reason: ${link.reason ?? "unknown"}`);
-                    lines.push(`   target: ${link.target}`);
-                }
-            });
-        }
-        if (responseModeAtLeast(responseMode, "verbose")) {
-            lines.push("");
-            appendIndexNoteCandidates(lines, result.indexNoteCandidates);
-        }
-        return textResult(lines.join("\n"));
-    });
-    server.tool("list_backlinks", "指定ノートへのバックリンク一覧を返します。", {
-        identifier: z.string().min(1),
-        limit: z.number().int().min(1).max(100).optional().describe("最大件数 (default: 20)"),
-        response_mode: responseModeSchema,
-    }, async ({ identifier, limit, response_mode }) => {
-        const responseMode = normalizeResponseMode(response_mode);
-        const result = await store.listBacklinks({
-            identifier,
-            limit: limit ?? 20,
-        });
-        const summary = summarizeBacklinksResponse({
-            indexLike: result.indexLike,
-            backlinkCount: result.backlinks.length,
-            boundaryWarningCount: result.boundaryWarnings.length,
-            firstBacklinkTitle: result.backlinks[0]?.title,
-            indexCandidateTitle: result.indexNoteCandidates[0]?.title,
-        });
-        const lines = [];
-        lines.push(`target: ${result.target.title}`);
-        lines.push(`project: ${result.project}`);
-        appendStorageContext(lines);
-        appendScopeLabel(lines, TOOL_SCOPE_LABELS.list_backlinks);
-        lines.push(`response_mode: ${responseMode}`);
-        appendReadResponseSummary(lines, summary);
-        appendResponsibilityWarning(lines, result.boundaryWarnings);
-        if (responseModeAtLeast(responseMode, "verbose")) {
-            appendIndexLike(lines, result.indexLike, result.indexReasons, "target");
-        }
-        appendBoundaryWarnings(lines, result.boundaryWarnings);
-        lines.push(`backlinks: ${result.backlinks.length}`);
-        lines.push("");
-        if (result.backlinks.length === 0) {
-            lines.push("バックリンクは見つかりませんでした。");
-        }
-        else {
-            result.backlinks.forEach((item, index) => {
-                lines.push(`${index + 1}. ${item.title}`);
-                lines.push(`   count: ${item.count}`);
-                if (responseModeAtLeast(responseMode, "standard")) {
-                    lines.push(`   file: ${item.filePath}`);
-                    lines.push(`   updated: ${item.updated}`);
-                }
-                item.examples.forEach((example) => {
-                    lines.push(`   example: ${example}`);
-                });
-            });
-        }
-        if (responseModeAtLeast(responseMode, "verbose")) {
-            lines.push("");
-            appendIndexNoteCandidates(lines, result.indexNoteCandidates);
-        }
-        return textResult(lines.join("\n"));
-    });
-    server.tool("context_bundle", "指定ノートを中心に、関連ノートを優先度付きで返します。", {
-        identifier: z.string().min(1),
-        limit: z.number().int().min(1).max(30).optional().describe("最大件数 (default: 8)"),
-        response_mode: responseModeSchema,
-    }, async ({ identifier, limit, response_mode }) => {
-        const responseMode = normalizeResponseMode(response_mode);
-        const result = await store.contextBundle({
-            identifier,
-            limit: limit ?? 8,
-        });
-        const summary = summarizeContextBundleResponse({
-            sourceIndexLike: result.source.indexLike,
-            bundleItemCount: result.items.length,
-            boundaryWarningCount: result.source.boundaryWarnings.length,
-            firstBundleItemTitle: result.items[0]?.title,
-            indexCandidateTitle: result.indexNoteCandidates[0]?.title,
-        });
-        const lines = [];
-        lines.push(`source: ${result.source.title}`);
-        lines.push(`project: ${result.project}`);
-        appendStorageContext(lines);
-        appendScopeLabel(lines, TOOL_SCOPE_LABELS.context_bundle);
-        lines.push(`response_mode: ${responseMode}`);
-        appendReadResponseSummary(lines, summary);
-        appendResponsibilityWarning(lines, result.source.boundaryWarnings);
-        if (responseModeAtLeast(responseMode, "standard")) {
-            lines.push(`memory_kind: ${result.source.memoryKind}`);
-            lines.push(`file: ${result.source.filePath}`);
-        }
-        if (responseModeAtLeast(responseMode, "verbose")) {
-            appendIndexLike(lines, result.source.indexLike, result.source.indexReasons, "source");
-        }
-        appendBoundaryWarnings(lines, result.source.boundaryWarnings);
-        lines.push(`bundle_items: ${result.items.length}`);
-        lines.push("");
-        if (result.items.length === 0) {
-            lines.push("関連ノートは見つかりませんでした。");
-        }
-        else {
-            result.items.forEach((item, index) => {
-                lines.push(`${index + 1}. ${item.title}`);
-                lines.push(`   score: ${item.score}`);
-                if (responseModeAtLeast(responseMode, "standard")) {
-                    lines.push(`   memory_kind: ${item.memoryKind}`);
-                    lines.push(`   file: ${item.filePath}`);
-                }
-                if (responseModeAtLeast(responseMode, "verbose")) {
-                    lines.push(`   reasons: ${item.reasons.join(", ")}`);
-                }
-            });
-        }
-        if (responseModeAtLeast(responseMode, "verbose")) {
-            lines.push("");
-            appendIndexNoteCandidates(lines, result.indexNoteCandidates);
-        }
-        if (responseModeAtLeast(responseMode, "standard")) {
-            appendExplorationGuidance(lines, result.explorationGuidance);
-        }
-        return textResult(lines.join("\n"));
-    });
-    server.tool("memory_contract", "kioq の Memory Contract（構造化ルール）を返します。", {
-        response_mode: responseModeSchema,
-    }, async ({ response_mode }) => {
-        const responseMode = normalizeResponseMode(response_mode);
-        const plan = memoryContractResponsePlan(responseMode);
-        const summary = {
-            ...summarizeMemoryContractResponse(),
-            ...memoryContractResponseModeHint(responseMode),
-        };
-        const contract = store.getMemoryContract();
-        const lines = [];
-        appendStorageContext(lines);
-        appendScopeLabel(lines, TOOL_SCOPE_LABELS.memory_contract);
-        lines.push(`response_mode: ${responseMode}`);
-        appendAuditResponseSummary(lines, summary);
-        lines.push(`memory_contract_version: ${contract.version}`);
-        lines.push(`required_frontmatter: ${contract.requiredFrontmatter.join(", ")}`);
-        lines.push(`flow_required_frontmatter: ${contract.flowRequiredFrontmatter.join(", ")}`);
-        lines.push(`parent_markers: ${contract.parentLinkMarkers.join(", ")}`);
-        lines.push(`source_metadata_canonical_field: ${contract.optionalSourceMetadata.canonicalField}`);
-        lines.push(`source_metadata_auxiliary_fields: ${contract.optionalSourceMetadata.auxiliaryFields.join(", ")}`);
-        lines.push(`index_threshold_score_at_least: ${contract.indexNavigationPolicy.thresholds.scoreAtLeast}`);
-        lines.push(`index_threshold_index_sections_at_least: ${contract.indexNavigationPolicy.thresholds.indexSectionsAtLeast}`);
-        lines.push(`technical_debt_threshold_stale_flow_days: ${contract.technicalDebtPolicy.thresholds.staleFlowDays}`);
-        lines.push("sample_templates_available: stock, flow, index");
-        if (!plan.includePolicyRules) {
-            return textResult(lines.join("\n"));
-        }
-        lines.push("requirements:");
-        lines.push(`- min_resolved_links: ${contract.requirements.minResolvedLinks}`);
-        lines.push(`- min_backlinks: ${contract.requirements.minBacklinks}`);
-        lines.push(`- min_parent_links: ${contract.requirements.minParentLinks}`);
-        lines.push(`- min_related_links: ${contract.requirements.minRelatedLinks}`);
-        lines.push(`- max_unresolved_links: ${contract.requirements.maxUnresolvedLinks}`);
-        lines.push(`- min_tags: ${contract.requirements.minTags}`);
-        lines.push("flow_requirements:");
-        lines.push(`- min_resolved_links: ${contract.flowRequirements.minResolvedLinks}`);
-        lines.push(`- min_backlinks: ${contract.flowRequirements.minBacklinks}`);
-        lines.push(`- min_parent_links: ${contract.flowRequirements.minParentLinks}`);
-        lines.push(`- min_related_links: ${contract.flowRequirements.minRelatedLinks}`);
-        lines.push(`- max_unresolved_links: ${contract.flowRequirements.maxUnresolvedLinks}`);
-        lines.push(`- min_tags: ${contract.flowRequirements.minTags}`);
-        lines.push("optional_source_metadata:");
-        lines.push(`- canonical_field: ${contract.optionalSourceMetadata.canonicalField}`);
-        lines.push(`- auxiliary_fields: ${contract.optionalSourceMetadata.auxiliaryFields.join(", ")}`);
-        contract.optionalSourceMetadata.rules.forEach((rule) => {
-            lines.push(`- rule: ${rule}`);
-        });
-        lines.push("index_navigation_policy:");
-        lines.push(`- excluded_memory_kinds: ${contract.indexNavigationPolicy.excludedMemoryKinds.join(", ")}`);
-        lines.push(`- threshold_score_at_least: ${contract.indexNavigationPolicy.thresholds.scoreAtLeast}`);
-        lines.push(`- threshold_index_sections_at_least: ${contract.indexNavigationPolicy.thresholds.indexSectionsAtLeast}`);
-        lines.push(`- configurable_via_env: ${contract.indexNavigationPolicy.configurableVia.env.join(", ")}`);
-        lines.push(`- configurable_via_cli: ${contract.indexNavigationPolicy.configurableVia.cli.join(", ")}`);
-        if (plan.includePolicySignals) {
-            contract.indexNavigationPolicy.signals.forEach((signal) => {
-                lines.push(`- signal: ${signal.code} weight=${signal.weight} description=${signal.description}`);
-            });
-        }
-        contract.indexNavigationPolicy.rules.forEach((rule) => {
-            lines.push(`- rule: ${rule}`);
-        });
-        lines.push("technical_debt_policy:");
-        lines.push(`- signals: ${contract.technicalDebtPolicy.signals.join(", ")}`);
-        lines.push(`- stale_flow_states: ${contract.technicalDebtPolicy.staleFlowStates.join(", ")}`);
-        lines.push(`- threshold_stale_flow_days: ${contract.technicalDebtPolicy.thresholds.staleFlowDays}`);
-        lines.push(`- stale_flow_age_bucket_near_threshold: ${contract.technicalDebtPolicy.staleFlowAgeBuckets.nearThreshold}`);
-        lines.push(`- stale_flow_age_bucket_aging: ${contract.technicalDebtPolicy.staleFlowAgeBuckets.aging}`);
-        lines.push(`- stale_flow_age_bucket_long_stale: ${contract.technicalDebtPolicy.staleFlowAgeBuckets.longStale}`);
-        lines.push(`- cleanup_ratio_definition: ${contract.technicalDebtPolicy.cleanupRatioDefinition}`);
-        lines.push(`- cleanup_ready_count_definition: ${contract.technicalDebtPolicy.cleanupReadyCountDefinition}`);
-        lines.push(`- attention_note_count_definition: ${contract.technicalDebtPolicy.attentionNoteCountDefinition}`);
-        lines.push(`- dependency_direction_violation_count_definition: ${contract.technicalDebtPolicy.dependencyDirectionViolationCountDefinition}`);
-        lines.push(`- single_use_tag_candidate_count_definition: ${contract.technicalDebtPolicy.singleUseTagCandidateCountDefinition}`);
-        lines.push(`- title_body_mismatch_candidate_count_definition: ${contract.technicalDebtPolicy.titleBodyMismatchCandidateCountDefinition}`);
-        lines.push(`- unresolved_wikilinks_delta_status: ${contract.technicalDebtPolicy.unresolvedWikilinksDeltaStatus}`);
-        lines.push(`- configurable_via_env: ${contract.technicalDebtPolicy.configurableVia.env.join(", ")}`);
-        lines.push(`- configurable_via_cli: ${contract.technicalDebtPolicy.configurableVia.cli.join(", ")}`);
-        lines.push("response_mode_policy:");
-        lines.push(`- supported_read_tools: ${contract.responseModePolicy.supportedTools.read.join(", ")}`);
-        lines.push(`- supported_audit_tools: ${contract.responseModePolicy.supportedTools.audit.join(", ")}`);
-        lines.push(`- minimal: ${contract.responseModePolicy.modes.minimal}`);
-        lines.push(`- standard: ${contract.responseModePolicy.modes.standard}`);
-        lines.push(`- verbose: ${contract.responseModePolicy.modes.verbose}`);
-        contract.responseModePolicy.rules.forEach((rule) => {
-            lines.push(`- rule: ${rule}`);
-        });
-        if (plan.includeSampleTemplates) {
-            lines.push("");
-            lines.push("sample_template_stock:");
-            lines.push("```md");
-            contract.sampleTemplates.stock.forEach((line) => lines.push(line));
-            lines.push("```");
-            lines.push("");
-            lines.push("sample_template_flow:");
-            lines.push("```md");
-            contract.sampleTemplates.flow.forEach((line) => lines.push(line));
-            lines.push("```");
-            lines.push("");
-            lines.push("sample_template_index:");
-            lines.push("```md");
-            contract.sampleTemplates.index.forEach((line) => lines.push(line));
-            lines.push("```");
-        }
-        return textResult(lines.join("\n"));
-    });
-    server.tool("lint_structure", "構造化を促すために、ノート群の問題を診断して優先順位付きで返します。", {
+    server.tool("lint_structure", "ノート群の構造的問題を診断し、優先順位付きで返します。", {
         limit: z.number().int().min(1).max(200).optional().describe("返却する issue 最大件数 (default: 50)"),
         response_mode: responseModeSchema,
     }, async ({ limit, response_mode }) => {
@@ -914,19 +654,92 @@ async function main() {
         }
         return textResult(lines.join("\n"));
     });
-    server.tool("write_note", "ローカル markdown ノートを作成/更新します。", {
+    server.tool("write_note", "ノートを作成/更新します。note_type='flow' で進行中の問いを記録、それ以外で知識(stock)を記録します。origin で誰が起点かを記録し、engagement追跡の基盤になります。", {
         title: z.string().min(1),
-        content: z.string().min(1),
-        directory: z.string().min(1).optional().describe("default: KIOQ_DEFAULT_DIRECTORY または Inbox"),
+        content: z.string().min(1).describe("note_type='flow' の場合は ## Notes セクションの本文"),
+        directory: z.string().min(1).optional().describe("default: stock→KIOQ_DEFAULT_DIRECTORY, flow→Flow"),
         tags: z.array(z.string()).optional(),
-        note_type: z.string().optional().describe("例: note / decision / task"),
-    }, async ({ title, content, directory, tags, note_type }) => {
+        note_type: z.string().optional().describe("stock(default) / flow / note / decision / task"),
+        origin: z.enum(["human", "ai", "collaborative"]).optional().describe("誰が起点か (human=体験, ai=AI生成/抽出, collaborative=対話から)"),
+        created_via: z.enum(["experience", "dialogue", "extraction", "curation", "capture"]).optional().describe("生成経路"),
+        human_role: z.enum(["thinker", "architect", "curator", "reviewer"]).optional().describe("collaborative 時の人間の役割"),
+        question: z.string().optional().describe("flow 時の問い (note_type='flow' で必須)"),
+        next_action: z.string().optional().describe("flow 時の次のアクション (note_type='flow' で必須)"),
+        parent_stock: z.string().optional().describe("flow 時の親 stock identifier (note_type='flow' で必須)"),
+        related: z.array(z.string()).optional().describe("flow 時の追加関連リンク先"),
+        flow_state: z.string().optional().describe("flow 時の状態: capture / active / blocked / done / promoted / dropped"),
+    }, async ({ title, content, directory, tags, note_type, origin, created_via, human_role, question, next_action, parent_stock, related, flow_state }) => {
+        // Flow note path
+        if (note_type === "flow") {
+            if (!question || !next_action || !parent_stock) {
+                return textResult("error: note_type='flow' requires question, next_action, parent_stock");
+            }
+            const flowResult = await store.writeFlowNote({
+                title,
+                question,
+                nextAction: next_action,
+                parentStock: parent_stock,
+                related,
+                details: content,
+                directory,
+                tags,
+                flowState: flow_state,
+                origin,
+                createdVia: created_via,
+                humanRole: human_role,
+            });
+            const flowSummary = summarizeWriteFlowResponse({
+                operation: flowResult.operation,
+                unresolvedWikiLinkCount: flowResult.unresolvedWikiLinks.length,
+                boundaryWarningCount: flowResult.boundaryWarnings.length,
+                memoryContractStatus: flowResult.memoryContract.status,
+                duplicateWarningCount: flowResult.duplicateWarnings.length,
+                orphanWarning: flowResult.orphanWarning,
+                title: flowResult.title,
+                parentStockResolved: flowResult.parentStockResolved,
+                parentStock: flowResult.parentStock,
+            });
+            const flowLines = [
+                "flow ノートを作成/更新しました。",
+                `project: ${flowResult.project}`,
+                `scope_label: ${TOOL_SCOPE_LABELS.write_flow_note}`,
+                `primary_navigation_signal: ${flowSummary.primaryNavigationSignal}`,
+                `primary_quality_signal: ${flowSummary.primaryQualitySignal}`,
+                `next_recommended_action: ${flowSummary.nextRecommendedAction}`,
+                `operation: ${flowResult.operation}`,
+                `file: ${flowResult.relativePath}`,
+                `permalink: ${flowResult.permalink}`,
+                `title: ${flowResult.title}`,
+                `flow_state: ${flowResult.flowState}`,
+                `parent_stock: ${flowResult.parentStock}`,
+                `parent_stock_resolved: ${flowResult.parentStockResolved ? "yes" : "no"}`,
+                `link_health: ${flowResult.linkHealth.resolved}/${flowResult.linkHealth.total} resolved`,
+                `backlinks: ${flowResult.backlinkCount}`,
+                `orphan_warning: ${flowResult.orphanWarning ? "yes" : "no"}`,
+            ];
+            flowLines.splice(2, 0, ...[`storage_backend: ${config.github ? "github" : "filesystem"}`, `storage_root: ${config.root}`, ...(config.github ? [`storage_repo: ${config.github.owner}/${config.github.repo}`, `storage_branch: ${config.github.branch}`] : [])]);
+            if (flowSummary.nextRecommendedTarget) {
+                insertBeforeLine(flowLines, "next_recommended_action:", `next_recommended_target: ${flowSummary.nextRecommendedTarget}`);
+            }
+            appendConflictSummary(flowLines, summarizeNoConflict({ serverUpdated: flowResult.serverUpdated }));
+            appendResponsibilityWarning(flowLines, flowResult.boundaryWarnings);
+            appendStructureScore(flowLines, flowResult.structureScore);
+            appendMemoryContract(flowLines, flowResult.memoryContract);
+            appendUnresolvedWikiLinks(flowLines, flowResult.unresolvedWikiLinks);
+            appendDuplicateWarnings(flowLines, flowResult.duplicateWarnings);
+            await appendAutoProjectHealth(flowLines);
+            return textResult(flowLines.join("\n"));
+        }
+        // Stock/generic note path
         const result = await store.writeNote({
             title,
             content,
             directory,
             tags,
             noteType: note_type,
+            origin,
+            createdVia: created_via,
+            humanRole: human_role,
         });
         const summary = summarizeWriteNoteResponse({
             operation: result.operation,
@@ -979,84 +792,6 @@ async function main() {
         await appendAutoProjectHealth(lines);
         return textResult(lines.join("\n"));
     });
-    server.tool("write_flow_note", "flow ノートを構造テンプレート付きで作成/更新します。", {
-        title: z.string().min(1),
-        question: z.string().min(1),
-        next_action: z.string().min(1),
-        parent_stock: z.string().min(1),
-        related: z.array(z.string()).optional().describe("追加の関連リンク先"),
-        details: z.string().optional().describe("## Notes に入れる本文"),
-        directory: z.string().min(1).optional().describe("default: Flow"),
-        tags: z.array(z.string()).optional(),
-        flow_state: z.string().optional().describe("capture / active / blocked / done / promoted / dropped"),
-    }, async ({ title, question, next_action, parent_stock, related, details, directory, tags, flow_state }) => {
-        const result = await store.writeFlowNote({
-            title,
-            question,
-            nextAction: next_action,
-            parentStock: parent_stock,
-            related,
-            details,
-            directory,
-            tags,
-            flowState: flow_state,
-        });
-        const summary = summarizeWriteFlowResponse({
-            operation: result.operation,
-            unresolvedWikiLinkCount: result.unresolvedWikiLinks.length,
-            boundaryWarningCount: result.boundaryWarnings.length,
-            memoryContractStatus: result.memoryContract.status,
-            duplicateWarningCount: result.duplicateWarnings.length,
-            orphanWarning: result.orphanWarning,
-            title: result.title,
-            parentStockResolved: result.parentStockResolved,
-            parentStock: result.parentStock,
-        });
-        const lines = [
-            "flow ノートを作成/更新しました。",
-            `project: ${result.project}`,
-            `scope_label: ${TOOL_SCOPE_LABELS.write_flow_note}`,
-            `primary_navigation_signal: ${summary.primaryNavigationSignal}`,
-            `primary_quality_signal: ${summary.primaryQualitySignal}`,
-            `next_recommended_action: ${summary.nextRecommendedAction}`,
-            `operation: ${result.operation}`,
-            `file: ${result.relativePath}`,
-            `permalink: ${result.permalink}`,
-            `title: ${result.title}`,
-            `flow_state: ${result.flowState}`,
-            `parent_stock: ${result.parentStock}`,
-            `parent_stock_resolved: ${result.parentStockResolved ? "yes" : "no"}`,
-            `link_health: ${result.linkHealth.resolved}/${result.linkHealth.total} resolved`,
-            `backlinks: ${result.backlinkCount}`,
-            `orphan_warning: ${result.orphanWarning ? "yes" : "no"}`,
-        ];
-        lines.splice(2, 0, ...[
-            `storage_backend: ${config.github ? "github" : "filesystem"}`,
-            `storage_root: ${config.root}`,
-            ...(config.github
-                ? [`storage_repo: ${config.github.owner}/${config.github.repo}`, `storage_branch: ${config.github.branch}`]
-                : []),
-        ]);
-        if (summary.nextRecommendedTarget) {
-            insertBeforeLine(lines, "next_recommended_action:", `next_recommended_target: ${summary.nextRecommendedTarget}`);
-        }
-        appendConflictSummary(lines, summarizeNoConflict({ serverUpdated: result.serverUpdated }));
-        appendResponsibilityWarning(lines, result.boundaryWarnings);
-        appendStructureScore(lines, result.structureScore);
-        appendMemoryContract(lines, result.memoryContract);
-        appendBoundaryWarnings(lines, result.boundaryWarnings);
-        appendTemplateHints(lines, {
-            primary: "flow",
-            alternatives: ["stock", "index"],
-            reason: "進行中の問いと next_action を残すときは flow template を基準にする",
-            whenToSwitch: "知識として固まったら stock、再訪入口を作るなら index template を使う",
-        });
-        appendUnresolvedWikiLinks(lines, result.unresolvedWikiLinks);
-        appendUnresolvedLinkHints(lines, result.unresolvedLinkHints);
-        appendDuplicateWarnings(lines, result.duplicateWarnings);
-        await appendAutoProjectHealth(lines);
-        return textResult(lines.join("\n"));
-    });
     server.tool("promote_to_stock", "flow ノートを stock ノートへ昇格させ、flow 側の状態を promoted に更新します。", {
         flow_identifier: z.string().min(1),
         stock_title: z.string().min(1).optional(),

package/dist/src/noteStore.js

@@ -2048,6 +2048,9 @@ export class LocalNoteStore {
             unresolvedLinkHints,
         };
     }
+    async loadAllNotes() {
+        return this.loadProjectNotes();
+    }
     async loadProjectNotes() {
         const files = await this.storage.listMarkdownFiles();
         return Promise.all(files.map((relativePath) => this.loadNote(relativePath)));
@@ -2814,6 +2817,143 @@ export class LocalNoteStore {
             explorationGuidance: this.contextExplorationGuidance(notes, sourceNote, rankedNotes),
         };
     }
+    async orient(args) {
+        const notes = await this.loadProjectNotes();
+        const lookup = this.buildLookup(notes);
+        const thought = args.thought.trim();
+        // Record observation signal if present
+        if (args.observation && args.signalLog) {
+            const signalType = `human_${args.observation.signal}`;
+            const resolved = this.resolveWikiTarget(args.observation.note, lookup);
+            const noteId = resolved.status === "resolved" && resolved.note
+                ? resolved.note.permalink
+                : args.observation.note;
+            args.signalLog.record(signalType, noteId, thought.slice(0, 120));
+        }
+        // Record orient references as signals
+        if (args.references && args.signalLog) {
+            for (const ref of args.references) {
+                const resolved = this.resolveWikiTarget(ref, lookup);
+                const noteId = resolved.status === "resolved" && resolved.note
+                    ? resolved.note.permalink
+                    : ref;
+                args.signalLog.record("orient_referenced", noteId, thought.slice(0, 120));
+            }
+        }
+        const toOrientItem = (note, reason) => {
+            const engagement = args.engagementIndex?.get(note.permalink);
+            const snippet = note.body.slice(0, this.config.previewLength).trim();
+            return {
+                identifier: note.title,
+                title: note.title,
+                permalink: note.permalink,
+                snippet,
+                reason,
+                engagement: {
+                    contactCount: engagement?.contactCount ?? 0,
+                    lastContact: engagement?.lastContact ?? null,
+                    humanSignalCount: engagement?.humanSignalCount ?? 0,
+                    dominantSignal: engagement?.dominantSignal ?? null,
+                    aiReferenceCount: engagement?.aiReferenceCount ?? 0,
+                    origin: engagement?.origin ?? safeString(note.frontmatter.origin) ?? null,
+                    createdVia: engagement?.createdVia ?? safeString(note.frontmatter.created_via) ?? null,
+                },
+            };
+        };
+        // === Slot 1: relevant (search-based + engagement boost) ===
+        const relevant = [];
+        if (thought.length > 0) {
+            for (const note of notes) {
+                let score = this.noteScore(note, thought);
+                if (score <= 0)
+                    continue;
+                // Engagement boost
+                const eng = args.engagementIndex?.get(note.permalink);
+                if (eng) {
+                    if (eng.humanSignalCount > 0)
+                        score = Math.floor(score * 1.5);
+                    else if (eng.aiReferenceCount > 0)
+                        score = Math.floor(score * 1.2);
+                    else if (eng.contactCount === 0)
+                        score = Math.floor(score * 0.8);
+                }
+                relevant.push({ note, score, reason: "text_match" });
+            }
+            relevant.sort((a, b) => b.score - a.score);
+        }
+        // Record discovered notes as signals
+        if (args.signalLog) {
+            for (const item of relevant.slice(0, 5)) {
+                args.signalLog.record("orient_discovered", item.note.permalink, thought.slice(0, 120));
+            }
+        }
+        // === Slot 2: active_context (active flows + recent high-engagement) ===
+        const activeContext = [];
+        const relevantPermalinks = new Set(relevant.slice(0, 5).map((r) => r.note.permalink));
+        for (const note of notes) {
+            if (relevantPermalinks.has(note.permalink))
+                continue;
+            const flowState = safeString(note.frontmatter.flow_state);
+            if (flowState === "active" || flowState === "capture") {
+                activeContext.push({ note, reason: `active_flow (${flowState})` });
+                continue;
+            }
+            const eng = args.engagementIndex?.get(note.permalink);
+            if (eng && eng.contactCount >= 3 && eng.lastContact) {
+                const daysSinceContact = Math.floor((Date.now() - new Date(eng.lastContact).getTime()) / (1000 * 60 * 60 * 24));
+                if (daysSinceContact <= 7) {
+                    activeContext.push({ note, reason: `recent_high_engagement (${eng.contactCount} contacts)` });
+                }
+            }
+        }
+        // === Slot 3: discovery (untouched notes with tag/directory adjacency) ===
+        const discovery = [];
+        const usedPermalinks = new Set([
+            ...relevantPermalinks,
+            ...activeContext.map((a) => a.note.permalink),
+        ]);
+        // Extract tags from thought terms for tag adjacency
+        const thoughtTerms = new Set(thought.toLowerCase().split(/[\s\p{P}]+/u).filter((t) => t.length >= 2));
+        for (const note of notes) {
+            if (usedPermalinks.has(note.permalink))
+                continue;
+            const eng = args.engagementIndex?.get(note.permalink);
+            if (eng && eng.contactCount > 0)
+                continue;
+            let discoveryScore = 0;
+            let reasons = [];
+            // Tag adjacency
+            const tags = safeStringArray(note.frontmatter.tags);
+            for (const tag of tags) {
+                if (thoughtTerms.has(tag.toLowerCase())) {
+                    discoveryScore += 10;
+                    reasons.push(`tag:${tag}`);
+                }
+            }
+            // Weak text match (lower threshold than relevant)
+            if (thought.length > 0) {
+                const textScore = this.noteScore(note, thought);
+                if (textScore > 0) {
+                    discoveryScore += Math.min(textScore, 20);
+                    reasons.push("weak_text_match");
+                }
+            }
+            // Random serendipity factor
+            discoveryScore += Math.floor(Math.random() * 5);
+            if (discoveryScore > 0 || Math.random() < 0.02) {
+                if (reasons.length === 0)
+                    reasons.push("serendipity");
+                discovery.push({ note, score: discoveryScore, reason: reasons.join(", ") });
+            }
+        }
+        discovery.sort((a, b) => b.score - a.score);
+        return {
+            project: this.projectName,
+            relevant: relevant.slice(0, 5).map((r) => toOrientItem(r.note, r.reason)),
+            activeContext: activeContext.slice(0, 5).map((a) => toOrientItem(a.note, a.reason)),
+            discovery: discovery.slice(0, 3).map((d) => toOrientItem(d.note, d.reason)),
+        };
+    }
     async writeFlowNote(args) {
         await this.storage.ensureRoot();
         const flowState = (safeString(args.flowState)?.toLowerCase() ?? "capture");
@@ -2871,6 +3011,9 @@ export class LocalNoteStore {
                 next_action: nextAction,
                 parent_stock: parentStock,
             },
+            origin: args.origin,
+            createdVia: args.createdVia,
+            humanRole: args.humanRole,
         });
         const notes = await this.loadProjectNotes();
         const lookup = this.buildLookup(notes);
@@ -3029,6 +3172,15 @@ export class LocalNoteStore {
             created: safeString(existingFrontmatter.created) ?? date,
             updated: date,
         };
+        if (input.origin && !existingFrontmatter.origin) {
+            frontmatter.origin = input.origin;
+        }
+        if (input.createdVia && !existingFrontmatter.created_via) {
+            frontmatter.created_via = input.createdVia;
+        }
+        if (input.humanRole && !existingFrontmatter.human_role) {
+            frontmatter.human_role = input.humanRole;
+        }
         for (const [key, value] of Object.entries(patch)) {
             if (RESERVED_FRONTMATTER_KEYS.has(key)) {
                 continue;

package/dist/src/signalLog.js

@@ -0,0 +1,62 @@
+const SIGNAL_DIR = ".kioq";
+const SIGNAL_FILE = `${SIGNAL_DIR}/signals.jsonl`;
+export class SignalLog {
+    storage;
+    buffer = [];
+    flushPromise = null;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    record(op, note, ctx) {
+        this.buffer.push({
+            ts: new Date().toISOString(),
+            op,
+            note,
+            ctx,
+        });
+    }
+    recordBatch(entries) {
+        const ts = new Date().toISOString();
+        for (const entry of entries) {
+            this.buffer.push({ ts, op: entry.op, note: entry.note, ctx: entry.ctx });
+        }
+    }
+    async flush() {
+        if (this.buffer.length === 0)
+            return;
+        if (this.flushPromise) {
+            await this.flushPromise;
+        }
+        const entries = this.buffer.splice(0);
+        const lines = entries.map((e) => JSON.stringify(e)).join("\n") + "\n";
+        this.flushPromise = this.appendToLog(lines);
+        try {
+            await this.flushPromise;
+        }
+        finally {
+            this.flushPromise = null;
+        }
+    }
+    async load() {
+        try {
+            const content = await this.storage.readFile(SIGNAL_FILE);
+            return content
+                .split("\n")
+                .filter((line) => line.trim().length > 0)
+                .map((line) => JSON.parse(line));
+        }
+        catch {
+            return [];
+        }
+    }
+    async appendToLog(content) {
+        let existing = "";
+        try {
+            existing = await this.storage.readFile(SIGNAL_FILE);
+        }
+        catch {
+            // file doesn't exist yet
+        }
+        await this.storage.writeFile(SIGNAL_FILE, existing + content);
+    }
+}

package/dist/src/storage/githubStorage.js

@@ -38,6 +38,8 @@ export class GitHubStorage {
     fetchFn;
     execFileAsyncFn;
     setupValidated = false;
+    lastFetchMs = 0;
+    static FETCH_INTERVAL_MS = 10_000;
     constructor(githubConfig, rootPath, deps = {}) {
         this.githubConfig = githubConfig;
         this.rootPath = rootPath;
@@ -48,17 +50,21 @@ export class GitHubStorage {
         this.fetchFn = deps.fetchFn ?? fetch;
         this.execFileAsyncFn = deps.execFileAsyncFn ?? execFileAsync;
     }
-    // --- Reads: delegate to local clone ---
-    stat(relativePath) {
+    // --- Reads: delegate to local clone (with auto-refresh) ---
+    async stat(relativePath) {
+        await this.refreshIfStale();
         return this.local.stat(relativePath);
     }
-    readFile(relativePath) {
+    async readFile(relativePath) {
+        await this.refreshIfStale();
         return this.local.readFile(relativePath);
     }
-    readdir(relativePath) {
+    async readdir(relativePath) {
+        await this.refreshIfStale();
         return this.local.readdir(relativePath);
     }
-    listMarkdownFiles() {
+    async listMarkdownFiles() {
+        await this.refreshIfStale();
         return this.local.listMarkdownFiles();
     }
     // --- Writes: GitHub Git Data API ---
@@ -352,6 +358,7 @@ export class GitHubStorage {
                 cwd: this.rootPath,
                 timeout: 30_000,
             });
+            this.lastFetchMs = Date.now();
         }
         catch (error) {
             throw new Error(`${context}: ${this.normalizeExecError(error)}`);
@@ -365,6 +372,25 @@ export class GitHubStorage {
             // best-effort only
         }
     }
+    async refreshIfStale() {
+        const now = Date.now();
+        if (now - this.lastFetchMs < GitHubStorage.FETCH_INTERVAL_MS) {
+            return;
+        }
+        try {
+            const { stdout: localRef } = await this.execFileAsyncFn("git", ["rev-parse", `refs/heads/${this.branch}`], { cwd: this.rootPath, timeout: 5_000 });
+            await this.execFileAsyncFn("git", ["fetch", "--no-tags", "origin", this.branch], { cwd: this.rootPath, timeout: 15_000 });
+            const { stdout: remoteRef } = await this.execFileAsyncFn("git", ["rev-parse", `refs/remotes/origin/${this.branch}`], { cwd: this.rootPath, timeout: 5_000 });
+            this.lastFetchMs = Date.now();
+            if (localRef.trim() !== remoteRef.trim()) {
+                await this.pullLocal("git pull --ff-only failed during auto-refresh");
+            }
+        }
+        catch {
+            // best-effort: if fetch fails, proceed with stale data
+            this.lastFetchMs = Date.now();
+        }
+    }
     isRetryableBatchError(error) {
         return (error instanceof GitHubApiError && error.retryable)
             || this.isTransientNetworkError(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomingtoming/kioq",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Japanese-first local markdown MCP server",
   "type": "module",
   "bin": {