kibi-opencode 0.9.0 → 0.10.0

package/dist/file-entity-links.js

@@ -0,0 +1,254 @@
+// implements REQ-opencode-file-context-guidance-v1
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+import { loadKbSyncPaths } from "./file-filter.js";
+// ── Lightweight YAML parser (symbols.yaml subset) ───────────────────
+//
+// Handles:
+//   symbols:
+//     - id: SYM-xxx
+//       sourceFile: path/to/file
+//       links:
+//         - REQ-xxx
+//       relationships:
+//         - type: implements
+//           target: REQ-xxx
+//
+// And bare array format (no wrapping `symbols:` key):
+//     - id: SYM-xxx
+//       ...
+// implements REQ-opencode-file-context-guidance-v1
+export function parseSymbolsYaml(content) {
+    const entries = [];
+    const lines = content.split("\n");
+    let current = null;
+    let section = "none";
+    let pendingRel = null;
+    function flushRel() {
+        if (pendingRel?.type && pendingRel.target && current?.relationships) {
+            current.relationships.push({
+                type: pendingRel.type,
+                target: pendingRel.target,
+            });
+        }
+        pendingRel = null;
+    }
+    function flushEntry() {
+        flushRel();
+        if (current?.id && current?.sourceFile) {
+            entries.push(current);
+        }
+        current = null;
+        section = "none";
+    }
+    for (const raw of lines) {
+        if (raw.trim().startsWith("#"))
+            continue;
+        // New entry: "  - id: ..."
+        const entryMatch = raw.match(/^\s+-\s+id:\s*(.+)$/);
+        if (entryMatch) {
+            flushEntry();
+            const entryId = entryMatch[1];
+            if (entryId === undefined)
+                continue;
+            current = { id: entryId.trim(), links: [], relationships: [] };
+            section = "none";
+            continue;
+        }
+        if (!current)
+            continue;
+        // sourceFile
+        const srcMatch = raw.match(/^\s+sourceFile:\s*(.+)$/);
+        if (srcMatch) {
+            const sourceFile = srcMatch[1];
+            if (sourceFile === undefined)
+                continue;
+            current.sourceFile = sourceFile.trim();
+            section = "none";
+            continue;
+        }
+        // links section header
+        if (/^\s+links:\s*$/.test(raw)) {
+            flushRel();
+            section = "links";
+            continue;
+        }
+        // relationships section header
+        if (/^\s+relationships:\s*$/.test(raw)) {
+            flushRel();
+            section = "relationships";
+            continue;
+        }
+        // Link item: "      - REQ-xxx"
+        if (section === "links") {
+            const linkMatch = raw.match(/^\s+-\s+(REQ-[A-Za-z0-9_-]+)\s*$/);
+            if (linkMatch) {
+                const linkId = linkMatch[1];
+                if (linkId !== undefined && current.links) {
+                    current.links.push(linkId);
+                }
+                continue;
+            }
+        }
+        // Relationship type: "      - type: implements"
+        if (section === "relationships") {
+            const relTypeMatch = raw.match(/^\s+-\s+type:\s*(.+)$/);
+            if (relTypeMatch) {
+                flushRel();
+                const relationType = relTypeMatch[1];
+                if (relationType === undefined)
+                    continue;
+                pendingRel = { type: relationType.trim() };
+                continue;
+            }
+            // Relationship target: "        target: REQ-..."
+            const relTargetMatch = raw.match(/^\s+target:\s*(.+)$/);
+            if (relTargetMatch && pendingRel) {
+                const target = relTargetMatch[1];
+                if (target === undefined)
+                    continue;
+                pendingRel.target = target.trim();
+                continue;
+            }
+        }
+    }
+    flushEntry();
+    return entries;
+}
+// ── Doc-path identity mapping ───────────────────────────────────────
+const DOC_ENTITY_PATTERN = /^(REQ|SCEN|TEST|ADR|FLAG|EVT|FACT)-[A-Za-z0-9_-]+\.md$/;
+// implements REQ-opencode-file-context-guidance-v1
+function resolveDocPathIdentity(relPath, syncPaths) {
+    const basename = path.posix.basename(relPath);
+    if (!DOC_ENTITY_PATTERN.test(basename))
+        return null;
+    const entityId = basename.replace(/\.md$/, "");
+    // Check if the file lives under one of the configured doc roots
+    const docRootKeys = [
+        "requirements",
+        "scenarios",
+        "tests",
+        "adr",
+        "flags",
+        "events",
+        "facts",
+    ];
+    // Normalize the relative path for matching
+    const normalizedRel = relPath.split(path.sep).join("/");
+    for (const key of docRootKeys) {
+        const pattern = syncPaths[key];
+        if (!pattern)
+            continue;
+        // Strip glob from pattern to get the root dir prefix
+        // e.g. "documentation/requirements/**/*.md" → "documentation/requirements"
+        const rootDir = pattern.replace(/\/\*\*\/.*$/, "").replace(/\/+$/, "");
+        if (normalizedRel.startsWith(rootDir + "/")) {
+            return entityId;
+        }
+    }
+    // If no specific root matched but path starts with documentation/,
+    // still accept (covers default configuration)
+    return null;
+}
+// ── Symbols file resolution ─────────────────────────────────────────
+function readSymbolsManifest(worktree, syncPaths) {
+    const symbolsPathRaw = syncPaths.symbols;
+    if (!symbolsPathRaw)
+        return [];
+    const symbolsPath = path.isAbsolute(symbolsPathRaw)
+        ? symbolsPathRaw
+        : path.join(worktree, symbolsPathRaw);
+    if (!existsSync(symbolsPath))
+        return [];
+    const content = readFileSync(symbolsPath, "utf8");
+    return parseSymbolsYaml(content);
+}
+function normalizeFilePath(worktree, filePath) {
+    // Normalize to forward-slash relative path from worktree
+    const absPath = path.isAbsolute(filePath)
+        ? filePath
+        : path.resolve(worktree, filePath);
+    return path
+        .relative(worktree, absPath)
+        .split(path.sep)
+        .join("/");
+}
+// ── Public API ──────────────────────────────────────────────────────
+// implements REQ-opencode-file-context-guidance-v1
+export function getFileLinkedEntityIds(worktree, filePath) {
+    try {
+        const syncPaths = loadKbSyncPaths(worktree);
+        const relPath = normalizeFilePath(worktree, filePath);
+        // Check doc-path identity first
+        const docId = resolveDocPathIdentity(relPath, syncPaths);
+        if (docId) {
+            return { ids: [docId], source: "doc-path" };
+        }
+        // Try symbols manifest
+        const symbols = readSymbolsManifest(worktree, syncPaths);
+        const matchedRows = symbols.filter((s) => s.sourceFile === relPath);
+        if (matchedRows.length === 0) {
+            return { ids: [], source: "none" };
+        }
+        const seen = new Set();
+        const orderedIds = [];
+        // Priority order: implements → covered_by → executable_for
+        const relPriority = ["implements", "covered_by", "executable_for"];
+        // First pass: collect relationships grouped by priority type, preserving file order within each type
+        for (const priorityType of relPriority) {
+            for (const row of matchedRows) {
+                for (const r of row.relationships ?? []) {
+                    if (r.type === priorityType) {
+                        const id = r.target;
+                        if (!seen.has(id)) {
+                            seen.add(id);
+                            orderedIds.push(id);
+                            if (orderedIds.length >= 3)
+                                return { ids: orderedIds.slice(0, 3), source: "symbols" };
+                        }
+                    }
+                }
+            }
+        }
+        // Second pass: fall back to static links, preserving file order
+        for (const row of matchedRows) {
+            for (const l of row.links ?? []) {
+                if (!seen.has(l)) {
+                    seen.add(l);
+                    orderedIds.push(l);
+                    if (orderedIds.length >= 3)
+                        return { ids: orderedIds.slice(0, 3), source: "symbols" };
+                }
+            }
+        }
+        return { ids: orderedIds.slice(0, 3), source: "symbols" };
+    }
+    catch {
+        return { ids: [], source: "none" };
+    }
+}
+// implements REQ-opencode-file-context-guidance-v1
+export function getFileLinkedTargetsByType(worktree, filePath, relationshipTypes) {
+    try {
+        const syncPaths = loadKbSyncPaths(worktree);
+        const relPath = normalizeFilePath(worktree, filePath);
+        const symbols = readSymbolsManifest(worktree, syncPaths);
+        const matchedRows = symbols.filter((s) => s.sourceFile === relPath);
+        if (matchedRows.length === 0)
+            return [];
+        const targets = [];
+        const seen = new Set();
+        for (const row of matchedRows) {
+            for (const r of row.relationships ?? []) {
+                if (relationshipTypes.includes(r.type) && !seen.has(r.target)) {
+                    seen.add(r.target);
+                    targets.push(r.target);
+                }
+            }
+        }
+        return targets;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/file-operation-reminders.d.ts

@@ -0,0 +1,24 @@
+import type { RepoPosture } from "./repo-posture.js";
+import type { PathKind } from "./path-kind.js";
+import type { RiskClass } from "./risk-classifier.js";
+import type { ReminderKind } from "./file-operation-state.js";
+import type { E2eCoverageSignal } from "./e2e-coverage-signals.js";
+export interface LinkedEntityResult {
+    ids: string[];
+    source: "symbols" | "doc-path" | "none";
+}
+export interface DeriveFileOperationReminderParams {
+    normalizedPath: string;
+    lifecycle: "created" | "edited" | "deleted";
+    pathKind: PathKind;
+    linkedEntityResult: LinkedEntityResult;
+    e2eSignal: E2eCoverageSignal;
+    currentSemanticRisk: RiskClass;
+    posture: RepoPosture;
+}
+export interface DeriveFileOperationReminderResult {
+    lifecycleReminder: string | null;
+    e2eReminder: string | null;
+    reminderKindsToMark: ReminderKind[];
+}
+export declare function deriveFileOperationReminder(params: DeriveFileOperationReminderParams): DeriveFileOperationReminderResult;

package/dist/file-operation-reminders.js

@@ -0,0 +1,55 @@
+// ── Lifecycle reminder text ─────────────────────────────────────
+const NEW_FILE_REMINDER = "- New file detected. Add or update the necessary Kibi entities and traceability before completing this task.";
+const DELETED_WITH_IDS_REMINDER = (ids) => `- Deleted file had linked Kibi entities: ${ids}. Update Kibi to keep traceability accurate.`;
+const DELETED_NO_IDS_REMINDER = "- Deleted file had no linked Kibi entities. Update Kibi if this removal changes documented behavior or traceability.";
+// ── Main exported function ────────────────────────────────────
+// implements REQ-opencode-file-context-guidance-v1
+export function deriveFileOperationReminder(params) {
+    const { lifecycle, pathKind, linkedEntityResult, e2eSignal, posture, } = params;
+    // Check if posture allows lifecycle reminders
+    const isAuthoritativePosture = posture === "root_active" || posture === "hybrid_root_plus_vendored";
+    // Derive lifecycle reminder
+    let lifecycleReminder = null;
+    const reminderKindsToMark = [];
+    if (isAuthoritativePosture) {
+        if (lifecycle === "created") {
+            // Only emit create reminder for code files (not documentation, not KB docs)
+            if (pathKind === "code") {
+                lifecycleReminder = NEW_FILE_REMINDER;
+                reminderKindsToMark.push("kibi_write");
+            }
+        }
+        else if (lifecycle === "edited") {
+            // No generic lifecycle reminder for edited files
+            // Existing semantic risk guidance remains primary
+        }
+        else if (lifecycle === "deleted") {
+            const ids = linkedEntityResult.ids;
+            if (ids.length > 0) {
+                lifecycleReminder = DELETED_WITH_IDS_REMINDER(ids.join(", "));
+                reminderKindsToMark.push("kibi_delete");
+            }
+            else {
+                lifecycleReminder = DELETED_NO_IDS_REMINDER;
+                reminderKindsToMark.push("kibi_delete");
+            }
+        }
+    }
+    // Derive e2e reminder (only when e2e signal exists)
+    // E2e reminders are NOT posture-gated - they're always relevant
+    let e2eReminder = null;
+    if (e2eSignal.level !== "none" && e2eSignal.reminderText !== null) {
+        e2eReminder = e2eSignal.reminderText;
+        if (lifecycle === "deleted") {
+            reminderKindsToMark.push("e2e_delete");
+        }
+        else {
+            reminderKindsToMark.push("e2e_write");
+        }
+    }
+    return {
+        lifecycleReminder,
+        e2eReminder,
+        reminderKindsToMark,
+    };
+}

package/dist/file-operation-state.d.ts

@@ -0,0 +1,29 @@
+export type FileLifecycle = "created" | "edited" | "deleted";
+export type ReminderKind = "kibi_write" | "kibi_delete" | "e2e_write" | "e2e_delete";
+export interface PendingLifecycleEvent {
+    /** Normalized file path (relative to worktree root). */
+    normalizedPath: string;
+    /** Coalesced lifecycle event for this path. */
+    lifecycle: FileLifecycle;
+    /** Timestamp (ms) of the lifecycle event. */
+    timestamp: number;
+}
+export interface FileOperationState {
+    /** Normalize file path relative to worktree root. */
+    normalizePath(filePath: string): string;
+    /** Record a lifecycle event for a file, coalescing with existing events. */
+    recordLifecycle(filePath: string, lifecycle: FileLifecycle, timestamp?: number): void;
+    /** Peek at pending lifecycle event, preferring specified path if available. */
+    peekPending(preferredPath?: string): PendingLifecycleEvent | null;
+    /** Consume pending lifecycle event for a specific path. */
+    consumePending(filePath: string): void;
+    /** Check if a reminder has already been shown for a path/kind combo. */
+    hasShown(filePath: string, reminderKind: ReminderKind): boolean;
+    /** Mark a reminder as shown for a path/kind combo. */
+    markShown(filePath: string, reminderKind: ReminderKind): void;
+}
+export declare function createFileOperationState(opts: {
+    worktree: string;
+    /** Custom clock for testing. Defaults to Date.now. */
+    now?: () => number;
+}): FileOperationState;

package/dist/file-operation-state.js

@@ -0,0 +1,113 @@
+import * as path from "node:path";
+// ---------------------------------------------------------------------------
+// Factory function
+// ---------------------------------------------------------------------------
+export function createFileOperationState(opts) {
+    const worktree = opts.worktree;
+    const now = opts.now ?? Date.now;
+    // ---- Per-instance state (no module globals) ----
+    /**
+     * Pending lifecycle events keyed by normalized path.
+     * Each path has at most one coalesced lifecycle state.
+     */
+    const pendingLifecycleEvents = new Map();
+    /**
+     * Reminder suppression state: (normalized path + reminder kind) -> shown flag.
+     * Keeps path-aware, kind-aware suppression separate from GuidanceCache.
+     */
+    const reminderSuppression = new Map();
+    // ---- Internal helpers ----
+    /**
+     * Coalesce lifecycle events using precedence rules:
+     * - created + edited -> created
+     * - edited + edited -> edited
+     * - created|edited + deleted -> deleted
+     * - deleted + created|edited -> deleted
+     */
+    function coalesceLifecycle(existing, incoming) {
+        if (existing === undefined) {
+            return incoming;
+        }
+        // created + edited -> created
+        if (existing === "created" && incoming === "edited") {
+            return "created";
+        }
+        // edited + edited -> edited
+        if (existing === "edited" && incoming === "edited") {
+            return "edited";
+        }
+        // created|edited + deleted -> deleted
+        if ((existing === "created" || existing === "edited") && incoming === "deleted") {
+            return "deleted";
+        }
+        // deleted + created|edited -> deleted
+        if (existing === "deleted" && (incoming === "created" || incoming === "edited")) {
+            return "deleted";
+        }
+        // Fallback: use incoming
+        return incoming;
+    }
+    function normalizeSessionPath(filePath) {
+        if (path.isAbsolute(filePath)) {
+            const relativePath = path.relative(worktree, filePath);
+            // Keep absolute path if it escapes worktree
+            return relativePath.startsWith("..") ? filePath : relativePath;
+        }
+        // Normalize leading ./ and trailing slashes
+        const normalized = path.normalize(filePath);
+        return normalized.startsWith("./") ? normalized.slice(2) : normalized;
+    }
+    function getSuppressionKey(filePath, kind) {
+        const normalized = normalizeSessionPath(filePath);
+        return `${normalized}:${kind}`;
+    }
+    // ---- Public API ----
+    function normalizePath(filePath) {
+        return normalizeSessionPath(filePath);
+    }
+    function recordLifecycle(filePath, lifecycle, timestamp) {
+        const normalized = normalizeSessionPath(filePath);
+        const existing = pendingLifecycleEvents.get(normalized);
+        const coalesced = coalesceLifecycle(existing?.lifecycle, lifecycle);
+        pendingLifecycleEvents.set(normalized, {
+            normalizedPath: normalized,
+            lifecycle: coalesced,
+            timestamp: timestamp ?? now(),
+        });
+    }
+    function peekPending(preferredPath) {
+        if (preferredPath !== undefined) {
+            const normalized = normalizeSessionPath(preferredPath);
+            const preferred = pendingLifecycleEvents.get(normalized);
+            return preferred ?? null;
+        }
+        // No preferred path specified, return most recent pending event
+        let mostRecent = null;
+        for (const event of pendingLifecycleEvents.values()) {
+            if (mostRecent === null || event.timestamp > mostRecent.timestamp) {
+                mostRecent = event;
+            }
+        }
+        return mostRecent;
+    }
+    function consumePending(filePath) {
+        const normalized = normalizeSessionPath(filePath);
+        pendingLifecycleEvents.delete(normalized);
+    }
+    function hasShown(filePath, reminderKind) {
+        const key = getSuppressionKey(filePath, reminderKind);
+        return reminderSuppression.get(key) ?? false;
+    }
+    function markShown(filePath, reminderKind) {
+        const key = getSuppressionKey(filePath, reminderKind);
+        reminderSuppression.set(key, true);
+    }
+    return {
+        normalizePath,
+        recordLifecycle,
+        peekPending,
+        consumePending,
+        hasShown,
+        markShown,
+    };
+}

package/dist/idle-brief-audit.d.ts

@@ -0,0 +1,36 @@
+export interface AuditCursor {
+    lastTimestamp: string;
+    lastOperation: string;
+    entryCount: number;
+    fileSize: number;
+}
+export interface AuditDelta {
+    hasChanges: boolean;
+    entries: AuditEntry[];
+    newCursor: AuditCursor;
+    contentHash: string;
+}
+export interface AuditEntry {
+    timestamp: string;
+    operation: string;
+    entityId: string;
+    payload?: AuditEntityPayload | AuditRelationshipPayload | null;
+}
+export interface AuditEntityPayload {
+    kind: "entity";
+    entityType: string;
+    changeKind?: "created" | "updated";
+    title?: string;
+    source?: string;
+    textRef?: string;
+    properties: Record<string, unknown>;
+}
+export interface AuditRelationshipPayload {
+    kind: "relationship";
+    relationshipType: string;
+    properties: Record<string, unknown>;
+}
+export declare function computeAuditDelta(workspaceRoot: string, branch: string, previousCursor: AuditCursor | null): AuditDelta;
+export declare function getLatestAuditCursor(workspaceRoot: string, branch: string): AuditCursor | null;
+export declare function getAuditTailCursor(workspaceRoot: string, branch: string): AuditCursor | null;
+export declare function guardBranchChanged(startBranch: string, currentBranch: string): boolean;