@mycodemap/mycodemap 1.9.0 → 2.7.0

package/dist/cli/env-contract/discovery.js

@@ -0,0 +1,249 @@
+// [META] since:2026-05-02 | owner:cli-team | stable:false
+// [WHY] Discover project environment contract items by scanning governance and executable source files.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+function sha256(content) {
+    return `sha256:${createHash('sha256').update(content).digest('hex')}`;
+}
+function safeReadFile(filePath) {
+    if (!existsSync(filePath))
+        return undefined;
+    try {
+        return readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function makeSnapshot(rootDir, relativePath) {
+    const fullPath = path.join(rootDir, relativePath);
+    if (!existsSync(fullPath))
+        return undefined;
+    try {
+        const content = readFileSync(fullPath, 'utf8');
+        const stat = statSync(fullPath);
+        return {
+            file: relativePath,
+            hash: sha256(content),
+            lastModified: stat.mtime.toISOString(),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+// ─── Source authority mapping ───────────────────────────────────────
+function classifyAuthority(filePath) {
+    if (filePath.startsWith('.githooks/') ||
+        filePath === 'package.json' ||
+        filePath.startsWith('vitest') ||
+        filePath.endsWith('.config.ts')) {
+        return 'executable';
+    }
+    if (filePath === 'AGENTS.md' ||
+        filePath.startsWith('docs/rules/') ||
+        filePath.startsWith('.mycodemap/rules/')) {
+        return 'governance';
+    }
+    if (filePath.startsWith('.mycodemap/assistants/')) {
+        return 'generated';
+    }
+    return 'example';
+}
+function makeSource(rootDir, relativePath, line) {
+    const fullPath = path.join(rootDir, relativePath);
+    if (!existsSync(fullPath))
+        return undefined;
+    try {
+        const content = readFileSync(fullPath, 'utf8');
+        return {
+            file: relativePath,
+            line,
+            hash: sha256(content),
+            authority: classifyAuthority(relativePath),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+// ─── Commit hook parsing ────────────────────────────────────────────
+function parseCommitHookTags(content) {
+    const match = content.match(/VALID_TAGS="([^"]+)"/);
+    if (!match)
+        return [];
+    return match[1].split(/\s+/).filter(Boolean);
+}
+function parseCommitHookFormat(content) {
+    // Extract format description from comment or echo lines
+    const formatMatch = content.match(/Format:\s*(.+)$/m);
+    if (formatMatch)
+        return formatMatch[1].trim();
+    return '[TAG] scope: message';
+}
+// ─── Item builders ──────────────────────────────────────────────────
+function buildRtkItem(rootDir) {
+    // RTK wrapper is documented in AGENTS.md or docs/rules/
+    const agentsSource = makeSource(rootDir, 'AGENTS.md');
+    if (!agentsSource)
+        return undefined;
+    return {
+        id: 'shell-rtk-wrapper',
+        category: 'execution',
+        severity: 'critical',
+        content: 'Shell commands must be wrapped with `rtk` for token-optimized execution. Prefix commands like `rtk git status`, `rtk npm run build`, `rtk npx vitest run`.',
+        sources: [agentsSource],
+    };
+}
+function buildCommitFormatItem(rootDir) {
+    const hookPath = '.githooks/commit-msg';
+    const hookContent = safeReadFile(path.join(rootDir, hookPath));
+    if (!hookContent)
+        return undefined;
+    const hookSource = makeSource(rootDir, hookPath);
+    if (!hookSource)
+        return undefined;
+    const tags = parseCommitHookTags(hookContent);
+    const format = parseCommitHookFormat(hookContent);
+    return {
+        id: 'commit-format',
+        category: 'commit',
+        severity: 'critical',
+        content: `Commit messages must use ${format} format with uppercase tags.`,
+        metadata: { validTags: tags },
+        sources: [hookSource],
+    };
+}
+function buildTestEntryItem(rootDir) {
+    // Check package.json for test script
+    const pkgContent = safeReadFile(path.join(rootDir, 'package.json'));
+    if (!pkgContent)
+        return undefined;
+    try {
+        const pkg = JSON.parse(pkgContent);
+        const scripts = pkg.scripts;
+        if (!scripts?.test)
+            return undefined;
+        const pkgSource = makeSource(rootDir, 'package.json');
+        if (!pkgSource)
+            return undefined;
+        return {
+            id: 'test-entry-vitest',
+            category: 'execution',
+            severity: 'critical',
+            content: `Tests run with \`${scripts.test}\`. Use \`${scripts.test}\` or \`npx vitest run\` directly, not \`npm test\` when RTK is available.`,
+            sources: [pkgSource],
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function buildQueryPriorityItem(rootDir) {
+    const agentsSource = makeSource(rootDir, 'AGENTS.md');
+    if (!agentsSource)
+        return undefined;
+    return {
+        id: 'codemap-query-priority',
+        category: 'retrieval',
+        severity: 'high',
+        content: 'CodeMap CLI query/analyze/deps/impact should be tried before raw grep/rg for code search. Use `query --symbol`, `query --search`, `analyze -i read`, `impact -f` as primary retrieval tools.',
+        sources: [agentsSource],
+    };
+}
+function buildRealScenarioValidationItem(rootDir) {
+    const testingSource = makeSource(rootDir, 'docs/rules/testing.md');
+    if (!testingSource)
+        return undefined;
+    return {
+        id: 'real-scenario-validation',
+        category: 'validation',
+        severity: 'high',
+        content: 'Real filesystem/subprocess or transport evidence and at least one failure scenario are required. Pure mock-only tests are not sufficient verification.',
+        sources: [testingSource],
+    };
+}
+// ─── Conflict detection ─────────────────────────────────────────────
+function detectConflicts(rootDir) {
+    const conflicts = [];
+    // Check commit tag case: hook enforces uppercase, docs might show lowercase
+    const hookContent = safeReadFile(path.join(rootDir, '.githooks/commit-msg'));
+    const agentsContent = safeReadFile(path.join(rootDir, 'AGENTS.md'));
+    if (hookContent && agentsContent) {
+        const hookTags = parseCommitHookTags(hookContent);
+        const hasUppercase = hookTags.every((tag) => tag === tag.toUpperCase());
+        if (hasUppercase && hookTags.length > 0) {
+            // Check if AGENTS.md or other docs reference lowercase tags
+            const lowerCaseRef = agentsContent.match(/\b(feat|fix|docs|test|refactor|config)\b/i);
+            if (lowerCaseRef) {
+                conflicts.push({
+                    id: 'commit-tag-case',
+                    severity: 'medium',
+                    description: 'Commit tag case mismatch between hook and documentation',
+                    sources: [
+                        { file: '.githooks/commit-msg', value: hookTags.join(' ') },
+                        { file: 'AGENTS.md', value: lowerCaseRef[0] },
+                    ],
+                    recommendation: 'Hook enforces uppercase tags; documentation should align with hook enforcement.',
+                });
+            }
+        }
+    }
+    return conflicts;
+}
+export function discoverProjectEnvironmentContract(rootDir, options) {
+    const items = [];
+    const snapshots = [];
+    // Collect source snapshots for known source files
+    const knownSources = [
+        'AGENTS.md',
+        '.githooks/commit-msg',
+        'package.json',
+        'docs/rules/testing.md',
+        'vitest.config.ts',
+    ];
+    for (const relPath of knownSources) {
+        const snapshot = makeSnapshot(rootDir, relPath);
+        if (snapshot)
+            snapshots.push(snapshot);
+    }
+    // Build contract items
+    const rtkItem = buildRtkItem(rootDir);
+    if (rtkItem)
+        items.push(rtkItem);
+    const commitItem = buildCommitFormatItem(rootDir);
+    if (commitItem)
+        items.push(commitItem);
+    const testItem = buildTestEntryItem(rootDir);
+    if (testItem)
+        items.push(testItem);
+    const queryItem = buildQueryPriorityItem(rootDir);
+    if (queryItem)
+        items.push(queryItem);
+    const validationItem = buildRealScenarioValidationItem(rootDir);
+    if (validationItem)
+        items.push(validationItem);
+    // Detect conflicts
+    const conflicts = detectConflicts(rootDir);
+    // Determine project profile
+    const profileName = options?.profileName ?? 'generic';
+    const projectSource = existsSync(path.join(rootDir, 'package.json'))
+        ? 'package.json'
+        : existsSync(path.join(rootDir, 'pyproject.toml'))
+            ? 'pyproject.toml'
+            : 'not-detected';
+    return {
+        schemaVersion: 'env-contract.v1',
+        generatedAt: options?.generatedAt ?? new Date().toISOString(),
+        projectProfile: {
+            name: profileName,
+            source: projectSource,
+            confidence: projectSource !== 'not-detected' ? 'high' : 'none',
+        },
+        items,
+        conflicts,
+        sourceSnapshots: snapshots,
+    };
+}
+//# sourceMappingURL=discovery.js.map

package/dist/cli/env-contract/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../../src/cli/env-contract/discovery.ts"],"names":[],"mappings":"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"}

package/dist/cli/env-contract/filters.d.ts

@@ -0,0 +1,10 @@
+import type { AgentType, ContractCategory, ContractItem, ProjectEnvironmentContract } from './types.js';
+export declare const DEFAULT_AGENT_FILTERS: Record<AgentType, readonly ContractCategory[]>;
+/**
+ * Filter contract items by agent type and optional category override.
+ *
+ * If `agentType` is unknown, falls back to 'default'.
+ * If `categoryOverride` is provided, it overrides the agent's default category set.
+ */
+export declare function filterContractForAgent(contract: ProjectEnvironmentContract, agentType: string, categoryOverride?: ContractCategory[]): ContractItem[];
+//# sourceMappingURL=filters.d.ts.map

package/dist/cli/env-contract/filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../../../src/cli/env-contract/filters.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAQvE,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,0BAA0B,EACpC,SAAS,EAAE,MAAM,EACjB,gBAAgB,CAAC,EAAE,gBAAgB,EAAE,GACpC,YAAY,EAAE,CAShB"}

package/dist/cli/env-contract/filters.js

@@ -0,0 +1,23 @@
+// [META] since:2026-05-02 | owner:cli-team | stable:false
+// [WHY] Agent-type filtering for Project Environment Contract items by category.
+export const DEFAULT_AGENT_FILTERS = {
+    explore: ['retrieval', 'validation'],
+    plan: ['retrieval', 'validation'],
+    edit: ['execution', 'commit', 'style', 'validation'],
+    worker: ['execution', 'commit', 'style', 'validation'],
+    review: ['retrieval', 'validation', 'style'],
+    verify: ['execution', 'validation'],
+    default: ['execution', 'commit', 'retrieval', 'validation', 'style'],
+};
+/**
+ * Filter contract items by agent type and optional category override.
+ *
+ * If `agentType` is unknown, falls back to 'default'.
+ * If `categoryOverride` is provided, it overrides the agent's default category set.
+ */
+export function filterContractForAgent(contract, agentType, categoryOverride) {
+    const effectiveType = agentType in DEFAULT_AGENT_FILTERS ? agentType : 'default';
+    const allowedCategories = categoryOverride ?? DEFAULT_AGENT_FILTERS[effectiveType];
+    return contract.items.filter((item) => allowedCategories.includes(item.category));
+}
+//# sourceMappingURL=filters.js.map

package/dist/cli/env-contract/filters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.js","sourceRoot":"","sources":["../../../src/cli/env-contract/filters.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,iFAAiF;AASjF,MAAM,CAAC,MAAM,qBAAqB,GAAmD;IACnF,OAAO,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC;IACpC,IAAI,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC;IACjC,IAAI,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,CAAC;IACpD,MAAM,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,CAAC;IACtD,MAAM,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,OAAO,CAAC;IAC5C,MAAM,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC;IACnC,OAAO,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,OAAO,CAAC;CAC5D,CAAC;AAEX;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,QAAoC,EACpC,SAAiB,EACjB,gBAAqC;IAErC,MAAM,aAAa,GACjB,SAAS,IAAI,qBAAqB,CAAC,CAAC,CAAE,SAAuB,CAAC,CAAC,CAAC,SAAS,CAAC;IAE5E,MAAM,iBAAiB,GAAG,gBAAgB,IAAI,qBAAqB,CAAC,aAAa,CAAC,CAAC;IAEnF,OAAO,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CACnC,iBAAuC,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CACjE,CAAC;AACJ,CAAC"}

package/dist/cli/env-contract/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './validation.js';
+export * from './discovery.js';
+export * from './filters.js';
+export * from './check.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/env-contract/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/env-contract/index.ts"],"names":[],"mappings":"AAGA,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/cli/env-contract/index.js

@@ -0,0 +1,8 @@
+// [META] since:2026-05-02 | owner:cli-team | stable:false
+// [WHY] Public exports for the Project Environment Contract subsystem.
+export * from './types.js';
+export * from './validation.js';
+export * from './discovery.js';
+export * from './filters.js';
+export * from './check.js';
+//# sourceMappingURL=index.js.map

package/dist/cli/env-contract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/env-contract/index.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,uEAAuE;AAEvE,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/cli/env-contract/reminder-engine.d.ts

@@ -0,0 +1,34 @@
+import type { AgentType } from './types.js';
+import type { ReminderLedger } from './reminder-ledger.js';
+import type { NormalizedReminderEvent } from './reminder-hook-runner.js';
+export interface ReminderRetrievalTarget {
+    cliCommand: string;
+    mcpToolCall: string;
+    checkCommand: string;
+}
+export interface ReminderRetrievalStatus {
+    available: boolean;
+    detail?: string;
+}
+export type ReminderDecision = {
+    kind: 'silent';
+    reason: 'already-reminded';
+} | {
+    kind: 'remind';
+    message: string;
+    target: ReminderRetrievalTarget;
+} | {
+    kind: 'warn';
+    message: string;
+    target: ReminderRetrievalTarget;
+    continue: true;
+};
+export interface ReminderDecisionDependencies {
+    ledger: ReminderLedger;
+    checkRetrieval: (role: AgentType) => Promise<ReminderRetrievalStatus> | ReminderRetrievalStatus;
+}
+export declare function buildReminderRetrievalTarget(role: AgentType): ReminderRetrievalTarget;
+export declare function buildReminderMessage(role: AgentType, target: ReminderRetrievalTarget): string;
+export declare function buildReminderWarning(role: AgentType, target: ReminderRetrievalTarget, detail?: string): string;
+export declare function decideReminder(event: NormalizedReminderEvent, dependencies: ReminderDecisionDependencies): Promise<ReminderDecision>;
+//# sourceMappingURL=reminder-engine.d.ts.map

package/dist/cli/env-contract/reminder-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reminder-engine.d.ts","sourceRoot":"","sources":["../../../src/cli/env-contract/reminder-engine.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAEzE,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAC;AAEvF,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,cAAc,CAAC;IACvB,cAAc,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC,uBAAuB,CAAC,GAAG,uBAAuB,CAAC;CACjG;AAED,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,SAAS,GAAG,uBAAuB,CAMrF;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,uBAAuB,GAAG,MAAM,CAM7F;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,uBAAuB,EAC/B,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAYR;AAED,wBAAsB,cAAc,CAClC,KAAK,EAAE,uBAAuB,EAC9B,YAAY,EAAE,4BAA4B,GACzC,OAAO,CAAC,gBAAgB,CAAC,CAsB3B"}

package/dist/cli/env-contract/reminder-engine.js

@@ -0,0 +1,51 @@
+// [META] since:2026-05-10 | owner:cli-team | stable:false
+// [WHY] Centralizes first-remind-then-silent decisions and visible retrieval failure messaging.
+export function buildReminderRetrievalTarget(role) {
+    return {
+        cliCommand: `mycodemap env-contract --for ${role} --json`,
+        mcpToolCall: `codemap_env_contract(agentType="${role}")`,
+        checkCommand: 'mycodemap env-contract --check',
+    };
+}
+export function buildReminderMessage(role, target) {
+    return [
+        `Before starting delegated ${role} work, retrieve the project environment contract.`,
+        `CLI: ${target.cliCommand}`,
+        `MCP: ${target.mcpToolCall}`,
+    ].join('\n');
+}
+export function buildReminderWarning(role, target, detail) {
+    const lines = [
+        `env-contract retrieval is currently unavailable for delegated ${role} work.`,
+        `Check: ${target.checkCommand}`,
+        `Retry: ${target.cliCommand}`,
+        `Fallback MCP: ${target.mcpToolCall}`,
+        'Delegated work may continue, but the reminder was not silently replaced.',
+    ];
+    if (detail) {
+        lines.push(`Failure: ${detail}`);
+    }
+    return lines.join('\n');
+}
+export async function decideReminder(event, dependencies) {
+    const firstSeen = dependencies.ledger.markFirstSeen(event.parentSessionId, event.role);
+    if (!firstSeen) {
+        return { kind: 'silent', reason: 'already-reminded' };
+    }
+    const target = buildReminderRetrievalTarget(event.role);
+    const retrievalStatus = await dependencies.checkRetrieval(event.role);
+    if (!retrievalStatus.available) {
+        return {
+            kind: 'warn',
+            continue: true,
+            target,
+            message: buildReminderWarning(event.role, target, retrievalStatus.detail),
+        };
+    }
+    return {
+        kind: 'remind',
+        target,
+        message: buildReminderMessage(event.role, target),
+    };
+}
+//# sourceMappingURL=reminder-engine.js.map

package/dist/cli/env-contract/reminder-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reminder-engine.js","sourceRoot":"","sources":["../../../src/cli/env-contract/reminder-engine.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,gGAAgG;AA2BhG,MAAM,UAAU,4BAA4B,CAAC,IAAe;IAC1D,OAAO;QACL,UAAU,EAAE,gCAAgC,IAAI,SAAS;QACzD,WAAW,EAAE,mCAAmC,IAAI,IAAI;QACxD,YAAY,EAAE,gCAAgC;KAC/C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,IAAe,EAAE,MAA+B;IACnF,OAAO;QACL,6BAA6B,IAAI,mDAAmD;QACpF,QAAQ,MAAM,CAAC,UAAU,EAAE;QAC3B,QAAQ,MAAM,CAAC,WAAW,EAAE;KAC7B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,IAAe,EACf,MAA+B,EAC/B,MAAe;IAEf,MAAM,KAAK,GAAG;QACZ,iEAAiE,IAAI,QAAQ;QAC7E,UAAU,MAAM,CAAC,YAAY,EAAE;QAC/B,UAAU,MAAM,CAAC,UAAU,EAAE;QAC7B,iBAAiB,MAAM,CAAC,WAAW,EAAE;QACrC,0EAA0E;KAC3E,CAAC;IACF,IAAI,MAAM,EAAE,CAAC;QACX,KAAK,CAAC,IAAI,CAAC,YAAY,MAAM,EAAE,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,KAA8B,EAC9B,YAA0C;IAE1C,MAAM,SAAS,GAAG,YAAY,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IACvF,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IACxD,CAAC;IAED,MAAM,MAAM,GAAG,4BAA4B,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,eAAe,GAAG,MAAM,YAAY,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACtE,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,CAAC;QAC/B,OAAO;YACL,IAAI,EAAE,MAAM;YACZ,QAAQ,EAAE,IAAI;YACd,MAAM;YACN,OAAO,EAAE,oBAAoB,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC;SAC1E,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,MAAM;QACN,OAAO,EAAE,oBAAoB,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC;KAClD,CAAC;AACJ,CAAC"}

package/dist/cli/env-contract/reminder-hook-runner.d.ts

@@ -0,0 +1,45 @@
+import type { AgentType } from './types.js';
+import { type ReminderRetrievalStatus } from './reminder-engine.js';
+import { type ReminderLedger } from './reminder-ledger.js';
+declare const CODEX_SEAM_EVENTS: readonly ["SessionStart", "UserPromptSubmit"];
+type CodexSeamEventName = (typeof CODEX_SEAM_EVENTS)[number];
+export interface NormalizedReminderEvent {
+    runtime: 'claude' | 'codex';
+    hookEventName: 'SubagentStart' | CodexSeamEventName;
+    parentSessionId: string;
+    role: AgentType;
+}
+export interface CodexSeamProbeResult {
+    hookEventName: CodexSeamEventName | null;
+    usable: boolean;
+    observedSessionFields: string[];
+    observedRoleFields: string[];
+    parentSessionId?: string;
+    role?: AgentType;
+    roleSource?: string;
+    reason?: string;
+    normalizedEvent?: NormalizedReminderEvent;
+}
+export type ReminderAction = {
+    kind: 'silent';
+} | {
+    kind: 'remind';
+    message: string;
+} | {
+    kind: 'warn';
+    message: string;
+};
+export interface ReminderHookDependencies {
+    ledger?: ReminderLedger;
+    checkRetrieval?: (role: AgentType) => Promise<ReminderRetrievalStatus> | ReminderRetrievalStatus;
+}
+export declare function probeCodexDelegatedStart(input: unknown): CodexSeamProbeResult;
+export declare function normalizeClaudeDelegatedStart(input: unknown): NormalizedReminderEvent | undefined;
+export declare function renderClaudeHookOutput(action: ReminderAction): string;
+export declare function renderCodexHookOutput(hookEventName: CodexSeamEventName, action: ReminderAction): string;
+export declare function buildReminderHookCommand(runtime: 'claude' | 'codex'): string;
+export declare function runClaudeReminderHook(input: unknown, dependencies?: ReminderHookDependencies): Promise<string>;
+export declare function runCodexReminderHook(input: unknown, dependencies?: ReminderHookDependencies): Promise<string>;
+export declare function runReminderHookFromStdin(runtime: 'claude' | 'codex', dependencies?: ReminderHookDependencies): Promise<string>;
+export {};
+//# sourceMappingURL=reminder-hook-runner.d.ts.map

package/dist/cli/env-contract/reminder-hook-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reminder-hook-runner.d.ts","sourceRoot":"","sources":["../../../src/cli/env-contract/reminder-hook-runner.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAkB,KAAK,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAY/E,QAAA,MAAM,iBAAiB,+CAAgD,CAAC;AAExE,KAAK,kBAAkB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAI7D,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC5B,aAAa,EAAE,eAAe,GAAG,kBAAkB,CAAC;IACpD,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACzC,MAAM,EAAE,OAAO,CAAC;IAChB,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,uBAAuB,CAAC;CAC3C;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC,uBAAuB,CAAC,GAAG,uBAAuB,CAAC;CAClG;AA+DD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CA2D7E;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,GAAG,SAAS,CAkBjG;AAYD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAarE;AAED,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,kBAAkB,EACjC,MAAM,EAAE,cAAc,GACrB,MAAM,CAaR;AAYD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAE5E;AAiDD,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,OAAO,EACd,YAAY,CAAC,EAAE,wBAAwB,GACtC,OAAO,CAAC,MAAM,CAAC,CAcjB;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,OAAO,EACd,YAAY,CAAC,EAAE,wBAAwB,GACtC,OAAO,CAAC,MAAM,CAAC,CAgBjB;AAkBD,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,QAAQ,GAAG,OAAO,EAC3B,YAAY,CAAC,EAAE,wBAAwB,GACtC,OAAO,CAAC,MAAM,CAAC,CAMjB"}