dsh-logicprobe 0.3.1

package/lib/index.js

@@ -0,0 +1,277 @@
+/**
+ * logicprobe — DeepSeek Harness native plugin for the Logic Probe toolbox.
+ * Injects the session-start gate text (claim-verification doctrine, 1% Rule,
+ * Red Flags, proactive suggestion) into the first model step of every agent
+ * session, mirroring the SessionStart hook the Claude Code plugin installs.
+ * The skill ships in this package's `skills/` directory and is registered at
+ * apply time into dsh's `ctx.skills` registry through the standard filesystem
+ * provider, so it appears in every session catalog without a manual copy step.
+ *
+ * Injection listens on agent/pre-step and appends the gate to the FIRST
+ * model step that runs, once per session (guarded by the session's durable
+ * history). Session-start inbox injection was dropped: a blank-session preset
+ * switch (agentPreset.select -> recompose) can clear the inbox before the
+ * first step, losing the gate for the whole session. The pre-step decision is
+ * the durable path - anchored/bootstrap presets that strip first-step injected
+ * reminders (skill catalog, AGENTS.md, gate plugins) simply defer this message
+ * to the first step after their promotion, and the history guard re-injects it
+ * there. The default gate text is the dsh-native adaptation of
+ * `hooks/session-start-content.md`: behavior rules
+ * (1% Rule / Red Flags / proactive suggestion) stay in sync, while
+ * presentation is adapted to dsh's native skill catalog — the trigger list
+ * lives in the skill description, not duplicated in the gate. Deployments
+ * override via Config.
+ *
+ * @module logicprobe-dsh
+ */
+import { fileURLToPath } from 'node:url';
+import z from '@deepseek-ai/schemastery';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { FileSystemSkillProvider } from '@deepseek-ai/dsh-skill-filesystem';
+import { logicProbeVerifyTool } from './tool.js';
+import { ENGINE_SCHEMA_VERSION } from './engine.js';
+export const name = 'logicprobe';
+// Skills are contributed through the registry service, which dsh-base always
+// mounts before bundle rows such as this one apply.
+export const inject = ['skills'];
+// Absolute path of the package's shipped skills directory. `lib/index.js`
+// lives one level below the package root, so `../skills` from the module URL
+// lands on `<package>/skills` regardless of where the package was installed.
+const SKILLS_DIR = fileURLToPath(new URL('../skills', import.meta.url));
+const GATE_PLUGIN_ID = 'logicprobe';
+const DEFAULT_GATE_CONTENT = `<EXTREMELY_IMPORTANT>
+Plugin logicprobe is active. Documents are not truth — code is. Verify every verifiable claim before accepting or acting on any design.
+
+**1% Rule**: If there is even a 1% chance the logicprobe skill applies — reviewing design documents, architecture specs, technical proposals, or refactoring plans that make claims about API names, file locations, enum values, mechanism feasibility, state machines, protocol logic, or behavioral guarantees ("always"/"never"/"guaranteed") — load it with the skill tool before responding. The cost of loading is trivial compared to the cost of a false claim.
+
+**Red Flags** — if you think any of these, STOP. You are rationalizing:
+
+| You think | Reality |
+|-----------|---------|
+| "This plan is too simple to verify" | The skill auto-classifies depth (LIGHTWEIGHT / STANDARD / ESCALATED). You don't decide. |
+| "I already know the file paths are correct" | Organic verification leaves no audit trail. Run Phase 0, append the "## Plan Verification" block. |
+| "I'll verify while implementing" | Verification happens before implementation, not during. |
+| "I can check this with reasoning alone" | Behavioral claims are verified with code/models, not intuition. One counter-example refutes a universal claim. |
+
+**Native verification path**: In dsh, prefer the \`logicprobe_verify\` tool for executable state-machine checks. The skill's Python harness remains the fallback for non-dsh hosts.
+
+**Proactive suggestion**: When a user asks code-level behavioral questions — "could this state machine deadlock", "is this retry limit safe", "check this timing sequence for bugs" — suggest logicprobe as an optional verification pass (do not auto-escalate).
+</EXTREMELY_IMPORTANT>`;
+export const Config = z.object({
+    enabled: z.boolean().default(true),
+    gateContent: z.string().default(DEFAULT_GATE_CONTENT),
+    interaction: z.union(['ask', 'auto', 'follow-approval']).default('follow-approval'),
+});
+function gateMessage(text) {
+    return createUserMessage({
+        content: [{ type: 'text', text }],
+        // `form` omitted — an undeclared context is the documented default.
+        source: { kind: 'plugin', plugin: GATE_PLUGIN_ID },
+    });
+}
+function lastApprovalPolicy(session) {
+    const events = session.events;
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event.type === 'approval/policy') {
+            return event.data?.policy === 'never' ? 'never' : 'ask';
+        }
+    }
+    return undefined;
+}
+function planModeActive(session) {
+    const events = session.events;
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event.type === 'plan/mode')
+            return event.data?.active === true;
+    }
+    return false;
+}
+function resolveInteraction(config, session) {
+    if (config.interaction === 'ask' || config.interaction === 'auto')
+        return config.interaction;
+    return lastApprovalPolicy(session) === 'never' ? 'auto' : 'ask';
+}
+function modeContextText(config, session) {
+    const interaction = resolveInteraction(config, session);
+    const lines = [
+        'logicprobe: use the `logicprobe_verify` tool for executable state-machine verification.',
+        interaction === 'auto'
+            ? 'logicprobe interaction=auto: do NOT call ask_user_question for model confirmation; run round-trip validation of the extracted transition table and mark the result UNCONFIRMED.'
+            : 'logicprobe interaction=ask: show the extracted transition table and get user confirmation before running verification.',
+    ];
+    if (planModeActive(session)) {
+        lines.push('Plan mode active: before exit_plan_mode, run logicprobe Phase 0 and append the "## Plan Verification" block to the plan file.');
+    }
+    return lines.join(' ');
+}
+/**
+ * Model-visible catalog entry (cordis_inspect_list / cordis_inspect_query):
+ * lets the model read this plugin's runtime status without guessing. Mirrors
+ * the registration pattern of the official dsh-tool-cordis host providers.
+ */
+function inspectProvider(config, isToolRegistered) {
+    return {
+        manifest: {
+            id: 'logicprobe',
+            description: 'Session-start gate injection and native verification tooling for the Logic Probe toolbox — folds the claim-verification doctrine (1% Rule / Red Flags / proactive suggestion) into the first model step of every agent session and registers the logicprobe_verify tool.',
+            methods: [
+                {
+                    name: 'status',
+                    description: 'Read gate injection status, interaction mode, tool registration state, and engine schema version.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {},
+                        additionalProperties: false,
+                    },
+                    outputSchema: {
+                        type: 'object',
+                        description: 'Gate-injection plugin status.',
+                        properties: {
+                            enabled: { type: 'boolean', description: 'Whether the gate folds into the first model step.' },
+                            gateContentLength: { type: 'integer', description: 'Length in characters of the injected gate text.' },
+                            interaction: { type: 'string', enum: ['ask', 'auto', 'follow-approval'], description: 'Configured interaction mode. follow-approval resolves per session from approval/policy.' },
+                            toolRegistered: { type: 'boolean', description: 'Whether the logicprobe_verify tool is registered on ctx.tools.' },
+                            engineSchemaVersion: { type: 'integer', description: 'Model schema version the bundled verification engine accepts.' },
+                        },
+                        required: ['enabled', 'gateContentLength', 'interaction', 'toolRegistered', 'engineSchemaVersion'],
+                        additionalProperties: false,
+                    },
+                },
+            ],
+        },
+        query: async (method) => {
+            if (method === 'status') {
+                return {
+                    enabled: config.enabled,
+                    gateContentLength: config.gateContent.length,
+                    interaction: config.interaction,
+                    toolRegistered: isToolRegistered(),
+                    engineSchemaVersion: ENGINE_SCHEMA_VERSION,
+                };
+            }
+            return null;
+        },
+    };
+}
+export function apply(ctx, config) {
+    // Optional services are registered opportunistically; base-bundle rows can
+    // mount after this row applies, so registration is retried on the first
+    // agent/pre-step — by then the app is fully booted.
+    let providerRegistered = false;
+    let toolRegistered = false;
+    let modeContextRegistered = false;
+    const registerProvider = () => {
+        if (providerRegistered)
+            return;
+        const inspect = ctx.get('cordisInspect');
+        if (inspect === undefined)
+            return;
+        try {
+            ctx.effect(() => inspect.register(inspectProvider(config, () => toolRegistered)), 'logicprobe: inspect provider');
+            providerRegistered = true;
+        }
+        catch (err) {
+            console.warn('[logicprobe] inspect provider registration failed', err);
+        }
+    };
+    const registerTool = () => {
+        if (toolRegistered)
+            return;
+        const tools = ctx.get('tools');
+        if (tools === undefined)
+            return;
+        try {
+            ctx.effect(() => tools.register(logicProbeVerifyTool), 'logicprobe: verify tool');
+            toolRegistered = true;
+        }
+        catch (err) {
+            console.warn('[logicprobe] logicprobe_verify tool registration failed', err);
+        }
+    };
+    const registerModeContext = () => {
+        if (modeContextRegistered)
+            return;
+        const systemPrompt = ctx.get('systemPrompt');
+        if (systemPrompt === undefined)
+            return;
+        try {
+            ctx.effect(() => systemPrompt.context({
+                name: 'logicprobe:mode',
+                order: 118,
+                text: (context) => {
+                    const agent = context.agent;
+                    if (agent === undefined)
+                        return '';
+                    return modeContextText(config, agent.session);
+                },
+            }), 'logicprobe: system prompt context');
+            modeContextRegistered = true;
+        }
+        catch (err) {
+            console.warn('[logicprobe] system prompt context registration failed', err);
+        }
+    };
+    const registerIntegrations = () => {
+        registerProvider();
+        registerTool();
+        registerModeContext();
+    };
+    registerIntegrations();
+    // Ship the bundled skill through the registry: reuse the standard
+    // filesystem provider over this package's own `skills/` directory, so
+    // catalog discovery, frontmatter parsing, and SKILL.md loading behave
+    // exactly like project/user skills while the plugin stays self-contained.
+    // Registration lands in the global registry layer (this row mounts at the
+    // profile root), so every agent preset sees the skill. `registerProvider`
+    // returns the effect disposer; its teardown unregisters and invalidates.
+    ctx.skills.registerProvider((control) => {
+        return new FileSystemSkillProvider(ctx, control, {
+            providerName: 'logicprobe',
+            includeDefaultRoots: false,
+            customSkillDirs: [SKILLS_DIR],
+        });
+    });
+    if (!config.enabled)
+        return;
+    // Inject the gate once per session on the FIRST model step that runs,
+    // instead of at session-start: session-start injection lands in the agent's
+    // inbox, which a blank-session preset switch (agentPreset.select ->
+    // recompose) can clear before the first step - the gate would then be lost
+    // for the whole session. The pre-step decision is the durable path a
+    // first-step injection takes: the gate is appended to the first step's
+    // decision and enters session history there, so every later step (and a
+    // resume) skips it. Anchored/bootstrap presets that strip first-step
+    // injected reminders (skill catalog, AGENTS.md, gate plugins) simply defer
+    // this message to the first step after their promotion - the history guard
+    // re-injects it there, so the gate still lands exactly once per session.
+    ctx.on('agent/pre-step', async ({ agent }, next) => {
+        const decision = await next();
+        if (decision.kind === 'reject')
+            return decision;
+        registerIntegrations();
+        if (gateInHistory(agent.session))
+            return decision;
+        return {
+            kind: 'enter',
+            messages: [...decision.messages, gateMessage(config.gateContent)],
+        };
+    });
+}
+/**
+ * Whether the gate already entered this session's durable history. The
+ * pre-step listener re-appends the gate until it does; once a step committed
+ * it, every later step (and a resume of a session that kept it) skips the
+ * injection. A session whose gate was dropped before any step ran (e.g. an
+ * inbox cleared by a blank-session preset switch) simply re-injects on the
+ * first step that runs.
+ */
+function gateInHistory(session) {
+    return session.events.some((event) => {
+        if (event.type !== 'user/message')
+            return false;
+        const source = event.data.source;
+        return source.kind === 'plugin' && source.plugin === GATE_PLUGIN_ID;
+    });
+}

package/lib/tool.js

@@ -0,0 +1,45 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { runVerification } from './engine.js';
+export const LOGICPROBE_VERIFY_TOOL_NAME = 'logicprobe_verify';
+/**
+ * Model-visible DSH tool wrapping the bundled TypeScript verification engine.
+ * The model passes a LogicModelV1 object; the engine validates it and returns
+ * the 14-check report. This is the dsh-native replacement for hand-filling the
+ * Python template shipped in the skill references.
+ */
+export const logicProbeVerifyTool = defineTool({
+    name: LOGICPROBE_VERIFY_TOOL_NAME,
+    description: 'Run executable state-machine verification (logicprobe). Takes a LogicModelV1 object with schemaVersion=1, init, states ({id, terminal?}), transitions ({from, event, to, guard?, updates?}), variables?, invariants?, concurrentPairs?, boundaryChecks?, resourcePairs?. Guards are structured ({variable, op, value} | {all} | {any} | {not}); invariants support never-states, var-in-range, and event-before-state. Returns a report with S1-S7 structural checks and A1-A7 adversarial probes including shortest counterexample paths. See skills/logicprobe/references/dsh-model-schema.md.',
+    parameters: {
+        model: {
+            type: 'json',
+            required: true,
+            description: 'LogicModelV1 state machine model to verify.',
+        },
+        maxStates: {
+            type: 'integer',
+            description: 'Maximum runtime states to explore. Default 10000.',
+        },
+        maxPermutationEvents: {
+            type: 'integer',
+            description: 'Maximum event count for A3 order permutation. Default 5.',
+        },
+    },
+    output: {
+        schema: {
+            type: 'json',
+            description: 'logicprobe verification report with summary and per-check findings.',
+        },
+        render(_args, value) {
+            return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+        },
+    },
+    timeoutMs: 10_000,
+    isConcurrencySafe: () => true,
+    async execute(args) {
+        return runVerification(args.model, {
+            maxStates: args.maxStates,
+            maxPermutationEvents: args.maxPermutationEvents,
+        });
+    },
+});

package/lib/types/engine.d.ts

@@ -0,0 +1,133 @@
+export declare const ENGINE_SCHEMA_VERSION = 1;
+export type VarValue = number | boolean;
+export type GuardOp = '==' | '!=' | '<' | '<=' | '>' | '>=';
+export interface LeafGuard {
+    variable: string;
+    op: GuardOp;
+    value: VarValue;
+}
+export interface AllGuard {
+    all: GuardNode[];
+}
+export interface AnyGuard {
+    any: GuardNode[];
+}
+export interface NotGuard {
+    not: GuardNode;
+}
+export type GuardNode = LeafGuard | AllGuard | AnyGuard | NotGuard;
+export interface StateSpec {
+    id: string;
+    terminal?: boolean;
+}
+export interface UpdateSpec {
+    variable: string;
+    op: 'set' | 'inc' | 'dec';
+    value?: number;
+}
+export interface TransitionSpec {
+    from: string;
+    event: string;
+    to: string;
+    /** Absent guard is the else/default branch for the same (from, event) group. */
+    guard?: GuardNode;
+    updates?: UpdateSpec[];
+}
+export interface VariableSpec {
+    name: string;
+    kind: 'integer' | 'boolean';
+    init: number | boolean;
+    min?: number;
+    max?: number;
+}
+export type InvariantSpec = {
+    id: string;
+    description: string;
+    kind: 'never-states';
+    states: string[];
+} | {
+    id: string;
+    description: string;
+    kind: 'var-in-range';
+    variable: string;
+    min?: number;
+    max?: number;
+} | {
+    id: string;
+    description: string;
+    kind: 'event-before-state';
+    event: string;
+    state: string;
+};
+export interface ResourcePairSpec {
+    resource: string;
+    acquireEvent: string;
+    releaseEvent: string;
+    failEvent?: string;
+}
+export interface BoundaryCheckSpec {
+    variable: string;
+    values: number[];
+}
+export interface LogicModelV1 {
+    schemaVersion: 1;
+    init: string;
+    states: StateSpec[];
+    transitions: TransitionSpec[];
+    variables?: VariableSpec[];
+    invariants?: InvariantSpec[];
+    concurrentPairs?: [string, string][];
+    boundaryChecks?: BoundaryCheckSpec[];
+    resourcePairs?: ResourcePairSpec[];
+}
+export interface VerificationOptions {
+    maxStates?: number;
+    maxPermutationEvents?: number;
+}
+export interface PathStep {
+    from: string;
+    event: string;
+    to: string;
+}
+export interface Finding {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+    path?: PathStep[];
+    evidence?: Record<string, unknown>;
+}
+export interface CheckResult {
+    id: string;
+    name: string;
+    status: 'pass' | 'fail' | 'skip';
+    detail: string;
+    findings: Finding[];
+}
+export interface VerificationReport {
+    ok: boolean;
+    schemaVersion: 1;
+    modelHash: string;
+    summary: {
+        states: number;
+        transitions: number;
+        errors: number;
+        warnings: number;
+        checksRun: number;
+        truncated?: boolean;
+    };
+    checks: CheckResult[];
+}
+export interface RuntimeState {
+    state: string;
+    vars: Record<string, VarValue>;
+}
+export declare function modelHash(model: LogicModelV1): string;
+export declare function validateModel(input: unknown): {
+    ok: true;
+    model: LogicModelV1;
+} | {
+    ok: false;
+    errors: string[];
+};
+export declare function guardVariables(guard: GuardNode | undefined): string[];
+export declare function runVerification(input: unknown, options?: VerificationOptions): VerificationReport;

package/lib/types/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * logicprobe — DeepSeek Harness native plugin for the Logic Probe toolbox.
+ * Injects the session-start gate text (claim-verification doctrine, 1% Rule,
+ * Red Flags, proactive suggestion) into the first model step of every agent
+ * session, mirroring the SessionStart hook the Claude Code plugin installs.
+ * The skill ships in this package's `skills/` directory and is registered at
+ * apply time into dsh's `ctx.skills` registry through the standard filesystem
+ * provider, so it appears in every session catalog without a manual copy step.
+ *
+ * Injection listens on agent/pre-step and appends the gate to the FIRST
+ * model step that runs, once per session (guarded by the session's durable
+ * history). Session-start inbox injection was dropped: a blank-session preset
+ * switch (agentPreset.select -> recompose) can clear the inbox before the
+ * first step, losing the gate for the whole session. The pre-step decision is
+ * the durable path - anchored/bootstrap presets that strip first-step injected
+ * reminders (skill catalog, AGENTS.md, gate plugins) simply defer this message
+ * to the first step after their promotion, and the history guard re-injects it
+ * there. The default gate text is the dsh-native adaptation of
+ * `hooks/session-start-content.md`: behavior rules
+ * (1% Rule / Red Flags / proactive suggestion) stay in sync, while
+ * presentation is adapted to dsh's native skill catalog — the trigger list
+ * lives in the skill description, not duplicated in the gate. Deployments
+ * override via Config.
+ *
+ * @module logicprobe-dsh
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "logicprobe";
+export declare const inject: string[];
+export type InteractionMode = 'ask' | 'auto' | 'follow-approval';
+export interface Config {
+    enabled: boolean;
+    gateContent: string;
+    interaction: InteractionMode;
+}
+export declare const Config: z<Schemastery.ObjectS<{
+    enabled: z<boolean, boolean>;
+    gateContent: z<string, string>;
+    interaction: z<"ask" | "auto" | "follow-approval", "ask" | "auto" | "follow-approval">;
+}>, Schemastery.ObjectT<{
+    enabled: z<boolean, boolean>;
+    gateContent: z<string, string>;
+    interaction: z<"ask" | "auto" | "follow-approval", "ask" | "auto" | "follow-approval">;
+}>>;
+export declare function apply(ctx: Context, config: Config): void;

package/lib/types/tool.d.ts

@@ -0,0 +1,8 @@
+export declare const LOGICPROBE_VERIFY_TOOL_NAME = "logicprobe_verify";
+/**
+ * Model-visible DSH tool wrapping the bundled TypeScript verification engine.
+ * The model passes a LogicModelV1 object; the engine validates it and returns
+ * the 14-check report. This is the dsh-native replacement for hand-filling the
+ * Python template shipped in the skill references.
+ */
+export declare const logicProbeVerifyTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/package.json

@@ -0,0 +1,81 @@
+{
+    "name": "dsh-logicprobe",
+    "version": "0.3.1",
+    "description": "Design document & plan claim verification — enumerate claims, verify against codebase facts, then escalate to logic-primitive verification (7 structural checks + 7 adversarial probes) for behavioral claims. Before/after model comparison for refactoring regression detection. Ships a native DeepSeek Harness (dsh) bundle that injects the claim-verification gate into the first model step.",
+    "type": "module",
+    "main": "lib/index.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/index.js"
+        },
+        "./cordis.patch.yml": "./cordis.patch.yml",
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "lib",
+        "src",
+        "skills",
+        "cordis.patch.yml"
+    ],
+    "dsh": {
+        "category": "skill",
+        "displayName": "逻辑探针",
+        "bundle": {
+            "patch": "./cordis.patch.yml"
+        }
+    },
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "typecheck": "tsc -p tsconfig.json --noEmit",
+        "test:engine": "npm run build && node tests/engine/run.mjs && node tests/apply-smoke.mjs"
+    },
+    "dependencies": {},
+    "peerDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+        "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+        "@deepseek-ai/dsh-skill-filesystem": "^0.1.0-rc.6",
+        "@deepseek-ai/schemastery": "^3.18.1",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+    },
+    "devDependencies": {
+        "@deepseek-ai/cordis": "^4.0.1",
+        "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-cordis-host-runner": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+        "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+        "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-skill-filesystem": "^0.1.0-rc.6",
+        "@deepseek-ai/schemastery": "^3.18.1",
+        "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+        "@types/node": "^20.0.0",
+        "typescript": "^5.0.0",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+        "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6"
+    },
+    "author": {
+        "name": "Amethyst Luna",
+        "url": "https://github.com/AmethystLuna"
+    },
+    "license": "MIT",
+    "repository": "https://github.com/AmethystLuna/logicprobe",
+    "keywords": [
+        "verification",
+        "fact-check",
+        "design-review",
+        "plan-review",
+        "state-machine",
+        "logic-verification",
+        "adversarial",
+        "refactoring",
+        "model-checking",
+        "agentskills",
+        "plugin",
+        "dsh"
+    ]
+}