dsh-doublecheck 0.5.0

package/lib/grill/provider.js

@@ -0,0 +1,189 @@
+/**
+ * Bundled skill provider for dsh-doublecheck's own `skills/` directory.
+ *
+ * The directory keeps the generic Agent Skills layout (`<name>/SKILL.md` with
+ * YAML frontmatter) so the assets stay liftable into any other Agent Skills
+ * ecosystem; this provider is the DSH-facing adapter that publishes them on
+ * `ctx.skills`.
+ *
+ * @module dsh-doublecheck/grill/provider
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BUNDLED_SKILL_RANK, isSkillName, } from '@deepseek-ai/dsh-skill';
+/** Provider name under which the registry files these skills. */
+export const PROVIDER_NAME = 'doublecheck';
+/** Skill origin bucket: these are host-bundled package assets. */
+const SOURCE = 'bundled';
+/** Invocation policy: both the model and the human slash-command surface may use these skills. */
+const INVOCATION = Object.freeze({ modelInvocable: true, userInvocable: true });
+/** Package skills root, resolved identically from `src/` and the built `lib/`. */
+const SKILLS_ROOT = fileURLToPath(new URL('../../skills/', import.meta.url));
+/**
+ * SkillProvider publishing the package's bundled `skills/` directory. List
+ * parses the frontmatter of every skill's SKILL.md; get re-reads the body so
+ * on-disk edits appear on the next load. A malformed asset is reported as an
+ * unreadable skill (skipped, logged), matching the registry's provider
+ * containment contract.
+ */
+export class BundledSkillProvider {
+    name = PROVIDER_NAME;
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * Discover the bundled skill candidates.
+     * @param options - lookup options; `signal` cancels directory and file reads.
+     * @returns the complete candidate list for the bundled root.
+     */
+    async list(options) {
+        // A bundled-root listing is a single directory read plus one parallel file
+        // read per skill; the abort signal still guards every read through `parse`.
+        const entries = await readdir(SKILLS_ROOT, { withFileTypes: true });
+        const parsedEntries = await Promise.all(entries
+            .filter(entry => entry.isDirectory())
+            .map(async (entry) => {
+            const directory = join(SKILLS_ROOT, entry.name);
+            const file = join(directory, 'SKILL.md');
+            const parsed = await this.parse(file, options.signal);
+            return parsed === undefined ? undefined : { parsed, file, directory };
+        }));
+        const candidates = [];
+        for (const entry of parsedEntries) {
+            if (entry === undefined)
+                continue;
+            const { parsed, file, directory } = entry;
+            candidates.push({
+                name: parsed.name,
+                description: parsed.description,
+                ...parsed.whenToUse !== undefined ? { whenToUse: parsed.whenToUse } : {},
+                invocation: INVOCATION,
+                provider: PROVIDER_NAME,
+                source: SOURCE,
+                rank: BUNDLED_SKILL_RANK,
+                locator: { file, directory },
+                resourceBase: { kind: 'directory', path: directory },
+                path: file,
+            });
+        }
+        return candidates.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    }
+    /**
+     * Load a complete bundled skill body.
+     * @param candidate - a candidate previously returned by {@link list}.
+     * @param options - lookup options; `signal` cancels the read.
+     * @returns the full skill definition, or `undefined` when the file no longer parses.
+     */
+    async get(candidate, options) {
+        const locator = candidate.locator;
+        const parsed = await this.parse(locator.file, options.signal);
+        if (parsed === undefined)
+            return undefined;
+        return {
+            name: parsed.name,
+            description: parsed.description,
+            ...parsed.whenToUse !== undefined ? { whenToUse: parsed.whenToUse } : {},
+            invocation: INVOCATION,
+            provider: PROVIDER_NAME,
+            source: SOURCE,
+            resourceBase: { kind: 'directory', path: locator.directory },
+            path: locator.file,
+            content: parsed.content,
+        };
+    }
+    async parse(file, signal) {
+        let raw;
+        try {
+            raw = await readFile(file, { encoding: 'utf8', signal });
+        }
+        catch (error) {
+            if (signal?.aborted === true)
+                throw error;
+            // A directory entry without SKILL.md is not a skill; any other read
+            // failure on our own bundled asset is an installation defect and
+            // propagates to the registry's provider containment.
+            if (hasErrorCode(error, 'ENOENT') || hasErrorCode(error, 'ENOTDIR'))
+                return undefined;
+            throw error;
+        }
+        const parsed = parseSkillAsset(raw);
+        if (parsed === undefined) {
+            this.ctx.logger.warn(`dsh-doublecheck: bundled skill file ${file} is malformed and was skipped`);
+            return undefined;
+        }
+        if (!isSkillName(parsed.name)) {
+            this.ctx.logger.warn(`dsh-doublecheck: bundled skill file ${file} has invalid skill name "${parsed.name}" and was skipped`);
+            return undefined;
+        }
+        return parsed;
+    }
+}
+/**
+ * Parse a bundled SKILL.md asset: YAML-frontmatter scalars plus the body.
+ * Only the three fields this package ships are read; the frontmatter itself
+ * stays standard Agent Skills YAML.
+ * @param raw - the full file text.
+ * @returns the parsed skill, or `undefined` when the file has no valid frontmatter.
+ */
+export function parseSkillAsset(raw) {
+    const firstLineEnd = raw.indexOf('\n');
+    if (firstLineEnd < 0)
+        return undefined;
+    const firstLine = raw.slice(0, firstLineEnd).replace(/\r$/, '');
+    if (firstLine !== '---')
+        return undefined;
+    const closing = findClosingFence(raw, firstLineEnd + 1);
+    if (closing === undefined)
+        return undefined;
+    const frontmatter = raw.slice(firstLineEnd + 1, closing.start);
+    const name = scalarField(frontmatter, 'name');
+    const description = scalarField(frontmatter, 'description');
+    if (name === undefined || description === undefined)
+        return undefined;
+    const whenToUse = scalarField(frontmatter, 'whenToUse');
+    return {
+        name,
+        description,
+        ...whenToUse !== undefined ? { whenToUse } : {},
+        content: raw.slice(closing.bodyStart).trim(),
+    };
+}
+/** Locate the closing `---` fence line and the body start after it. */
+function findClosingFence(raw, start) {
+    let lineStart = start;
+    while (lineStart <= raw.length) {
+        const nextNewline = raw.indexOf('\n', lineStart);
+        const lineEnd = nextNewline < 0 ? raw.length : nextNewline;
+        const line = raw.slice(lineStart, lineEnd).replace(/\r$/, '');
+        if (line === '---') {
+            return { start: lineStart, bodyStart: nextNewline < 0 ? raw.length : nextNewline + 1 };
+        }
+        if (nextNewline < 0)
+            return undefined;
+        lineStart = nextNewline + 1;
+    }
+    return undefined;
+}
+/** Read one `key: value` scalar line, stripping one layer of matching quotes. */
+function scalarField(frontmatter, key) {
+    for (const line of frontmatter.split('\n')) {
+        const match = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(line);
+        if (match === null || match[1] !== key)
+            continue;
+        const value = match[2].trim();
+        if (value.length === 0)
+            return undefined;
+        const quote = value[0];
+        if ((quote === '"' || quote === "'") && value.endsWith(quote) && value.length >= 2) {
+            return value.slice(1, -1);
+        }
+        return value;
+    }
+    return undefined;
+}
+/** Whether an arbitrary thrown value carries the given Node error code. */
+function hasErrorCode(error, code) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
+}

package/lib/guard/command.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The `/doublecheck` session command: inspect and steer the discipline gates
+ * from the conversation.
+ *
+ * - `status` — effective switch, configured modules, and the folded stage
+ *   facts (spec committed, red/green color, review on record).
+ * - `report` — folds the delivery report on the spot from the same durable
+ *   evidence the `doublecheck_report` tool reads (no verification workflow:
+ *   the report tool owns that path).
+ * - `on` / `off` — writes the durable `doublecheck/state` override (the fold
+ *   survives restarts, resumes, and forks — replay IS the state) and injects
+ *   a model-visible switch notice (`user/message`, plugin source).
+ *
+ * @module dsh-doublecheck/guard/command
+ */
+import type { CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands';
+import { Session } from '@deepseek-ai/dsh-session';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { TestRunDetection } from '../domain/evidence.ts';
+import type { Config, Snapshot } from './index.ts';
+export declare function hostStampsIgnorable(): boolean;
+/**
+ * The session's doublecheck master switch: the last `doublecheck/state` event,
+ * or the configured default when none is on record.
+ * @param events - the session log.
+ * @param fallback - `enableByDefault` from the guard config.
+ * @returns whether the discipline gates are enabled for this session.
+ */
+export declare function effectiveDoublecheckEnabled(events: readonly SessionEvent[], fallback: boolean): boolean;
+/** The closures the command reads; all live inside the guard's `apply` scope. */
+export interface CommandDeps {
+    config: Config;
+    /** The folded guard facts for a session (incremental fold, log-derived). */
+    snapshotOf: (session: Session) => Snapshot;
+    /** The compiled test-run detection shared with the tdd/adversary gates. */
+    detection: TestRunDetection;
+    /** Whether the host append surface stamps `ignorable` (see {@link hostStampsIgnorable}). */
+    stampsIgnorable: () => boolean;
+    /** Record a process-local switch override when the durable write is unavailable. */
+    setLocalOverride: (session: Session, enabled: boolean) => void;
+}
+/**
+ * Execute the `/doublecheck` command.
+ * @param deps - the guard closures the handler reads.
+ * @returns the command handler for `ctx.commands.register`.
+ */
+export declare function doublecheckHandler(deps: CommandDeps): (invocation: CommandInvocation) => CommandResult;

package/lib/guard/command.js

@@ -0,0 +1,132 @@
+/**
+ * The `/doublecheck` session command: inspect and steer the discipline gates
+ * from the conversation.
+ *
+ * - `status` — effective switch, configured modules, and the folded stage
+ *   facts (spec committed, red/green color, review on record).
+ * - `report` — folds the delivery report on the spot from the same durable
+ *   evidence the `doublecheck_report` tool reads (no verification workflow:
+ *   the report tool owns that path).
+ * - `on` / `off` — writes the durable `doublecheck/state` override (the fold
+ *   survives restarts, resumes, and forks — replay IS the state) and injects
+ *   a model-visible switch notice (`user/message`, plugin source).
+ *
+ * @module dsh-doublecheck/guard/command
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { Session, SessionId } from '@deepseek-ai/dsh-session';
+import { deriveReportVerdict, foldReportFacts, renderReportMarkdown } from "../domain/report.js";
+/**
+ * Whether this host's `Session.append` stamps the `ignorable` envelope marker.
+ * Detected once per process on a detached probe session: hosts without the
+ * surface (rc.6) accept and ignore the options bag, and writing the durable
+ * state event unmarked would make the session log unreadable to first-party
+ * readers — so the switch command falls back to in-memory switching there.
+ * @returns true when a `doublecheck/state` append comes back with the marker.
+ */
+let ignorableCapability;
+export function hostStampsIgnorable() {
+    if (ignorableCapability === undefined) {
+        try {
+            const probe = Session.create(SessionId('doublecheck-append-probe'));
+            const event = probe.append('doublecheck/state', { enabled: true }, { ignorable: true });
+            ignorableCapability = event.ignorable === true;
+        }
+        catch {
+            ignorableCapability = false;
+        }
+    }
+    return ignorableCapability;
+}
+/**
+ * The session's doublecheck master switch: the last `doublecheck/state` event,
+ * or the configured default when none is on record.
+ * @param events - the session log.
+ * @param fallback - `enableByDefault` from the guard config.
+ * @returns whether the discipline gates are enabled for this session.
+ */
+export function effectiveDoublecheckEnabled(events, fallback) {
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event?.type === 'doublecheck/state')
+            return event.data.enabled;
+    }
+    return fallback;
+}
+/** The switch notice injected after `/doublecheck on|off`. */
+function switchNotice(enabled, durable) {
+    const source = { kind: 'plugin', plugin: 'dsh-doublecheck', form: 'notice', summary: 'doublecheck state' };
+    const scope = durable
+        ? 'for this session'
+        : 'for this process only (this harness build predates the ignorable append surface, so the switch is not durable)';
+    const text = enabled
+        ? `Double-check discipline was switched ON ${scope} (changed by the user): the requirements grill, the red/green gates, and the delivery review are active again.`
+        : `Double-check discipline was switched OFF ${scope} (changed by the user): the discipline gates defer to the human approval chain until switched back on.`;
+    return createUserMessage({ content: [{ type: 'text', text }], source });
+}
+/**
+ * Execute the `/doublecheck` command.
+ * @param deps - the guard closures the handler reads.
+ * @returns the command handler for `ctx.commands.register`.
+ */
+export function doublecheckHandler(deps) {
+    const { config, snapshotOf, detection, stampsIgnorable, setLocalOverride } = deps;
+    return (invocation) => {
+        const agent = invocation.agent;
+        if (agent === undefined) {
+            return { kind: 'error', text: '/doublecheck needs an agent session to inspect.' };
+        }
+        const session = agent.session;
+        const input = invocation.rawInput.trim().toLowerCase();
+        const enabled = effectiveDoublecheckEnabled(session.events, config.enableByDefault);
+        if (input === 'status' || input === '') {
+            const snapshot = snapshotOf(session);
+            const discipline = snapshot.discipline;
+            return {
+                kind: 'success',
+                text: [
+                    `Double-check discipline is ${enabled ? 'ON' : 'OFF'} for this session. (/doublecheck on|off)`,
+                    `Modules: grill=${config.modules.grill ? 'on' : 'off'}, tdd=${config.modules.tdd ? 'on' : 'off'}, adversary=${config.modules.adversary ? 'on' : 'off'} (cordis.yml).`,
+                    `Stage: spec=${discipline.hasSpec ? 'committed' : 'missing'}, tests=${discipline.color}, review=${snapshot.lastReviewSeq >= 0 ? 'on record' : 'not run'}.`,
+                    'Usage: /doublecheck status|report|on|off',
+                ].join('\n'),
+            };
+        }
+        if (input === 'report') {
+            const facts = foldReportFacts(session.events, detection);
+            const report = {
+                ...facts,
+                verdict: deriveReportVerdict(facts, null),
+                verification: null,
+                path: null,
+                written: false,
+            };
+            return { kind: 'success', text: renderReportMarkdown(report) };
+        }
+        if (input !== 'on' && input !== 'off') {
+            return { kind: 'error', text: `Unknown /doublecheck argument "${invocation.rawInput.trim()}". Usage: /doublecheck status|report|on|off` };
+        }
+        const target = input === 'on';
+        if (enabled === target) {
+            return { kind: 'success', text: `Double-check discipline is already ${input.toUpperCase()} for this session.` };
+        }
+        // Adaptive durable write: only hosts that stamp `ignorable` may write the
+        // state event; on rc.6 the options bag is ignored and an unmarked foreign
+        // event would make the session log unreadable to first-party readers.
+        const durable = stampsIgnorable();
+        if (durable) {
+            ;
+            session.append('doublecheck/state', { enabled: target }, { ignorable: true });
+        }
+        else {
+            setLocalOverride(session, target);
+        }
+        agent.inject(switchNotice(target, durable));
+        return {
+            kind: 'success',
+            text: durable
+                ? `Double-check discipline ${input.toUpperCase()} for this session.`
+                : `Double-check discipline ${input.toUpperCase()} for this process only (not durable on this harness).`,
+        };
+    };
+}

package/lib/guard/index.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The discipline guard: dsh-doublecheck's soft enforcement plugin.
+ *
+ * Two gates compose on the documented `tools/pre-execute` /
+ * `tools/post-execute` / `agent/turn-stopping` extension points, both reading
+ * their facts from the durable session log alone:
+ *
+ * - **Grill gate** (`modules.grill`): a vague task with no committed
+ *   `doublecheck_spec` may not mutate implementation files.
+ * - **Red/green gate** (`modules.tdd`, v0.2): an implementation edit requires
+ *   a failing test run on record since the last passing run (the red step);
+ *   at turn end, edits without a passing run re-arm the green reminder.
+ *   Writing test files is always allowed — that is how the red step happens.
+ *
+ * The configured `intensity` picks the consequence for both gates:
+ *
+ * - `remind`: the call proceeds; a reminder rides the call's
+ *   `additionalContexts`, so the agent loop records it as a `user/message`
+ *   session event (model-visible ⟺ logged).
+ * - `warn`: the call is held for human approval through the approval seam
+ *   (`ask`); without an approval channel it denies.
+ * - `block`: the call is denied with corrective feedback.
+ *
+ * Resumed and forked sessions enforce identically. The package-internal
+ * `doublecheck/reminder` event announces each reaction for observers.
+ *
+ * @module dsh-doublecheck/guard
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type Schema from '@deepseek-ai/schemastery';
+import { type DisciplineState } from '../domain/stages.ts';
+import type { GuardIntensity } from '../events.ts';
+import { type ProseLanguage } from './prose.ts';
+export declare const name = "doublecheck-guard";
+export declare const inject: string[];
+/**
+ * Guard configuration. `intensity` is shared by all three gates; `modules`
+ * selects them. The `adversary` module (v0.3) dispatches a forked critic
+ * subagent at the turn boundary once the delivery reaches green.
+ */
+export interface Config {
+    /** Enforcement strength of the grill, red/green, and review gates. */
+    intensity: GuardIntensity;
+    /** Discipline module switches. */
+    modules: {
+        grill: boolean;
+        tdd: boolean;
+        adversary: boolean;
+    };
+    /** Model route for the adversary critic; null means the main model self-reviews. */
+    adversaryModel: string | null;
+    /** Subagent provider name the critic runs on (default `fork`). */
+    adversaryProvider: string;
+    /** Maximum structured findings injected into the session. */
+    adversaryMaxFindings: number;
+    /** Tools the critic may call (read-only by default; never mutation tools). */
+    adversaryTools: string[];
+    /** Hard time budget for one critic run before it settles as unavailable. */
+    adversaryTimeoutMs: number;
+    /** Mutation tool names both gates watch (default `edit`, `write`). */
+    guardTools: string[];
+    /** Task text longer than this many characters is never treated as vague. */
+    vagueTaskMaxChars: number;
+    /** Inject each gate's reminder at most once per session. */
+    remindOnce: boolean;
+    /** Language of the injected reminder/deny/review prose. */
+    language: ProseLanguage;
+    /** Master switch for sessions without a `doublecheck/state` override. */
+    enableByDefault: boolean;
+    /** Shell tool names that can run tests (default `bash`, `pwsh`). */
+    testToolNames: string[];
+    /** Regexes a shell command must match to count as a test run. */
+    testCommandPatterns: string[];
+    /** Regexes identifying test-file paths, exempt from the red gate. */
+    testFilePatterns: string[];
+}
+export declare const Config: Schema<Config>;
+/** Cached per-session guard facts, folded incrementally from the append-only log. */
+export interface Snapshot {
+    /** The log snapshot this fold last consumed; an append yields a new one. */
+    events: readonly SessionEvent[];
+    /** Number of events already folded. */
+    scanned: number;
+    /** Latest direct-user task text folded so far. */
+    latestUserText: string;
+    /** `isVagueTask` applied to `latestUserText`. */
+    vague: boolean;
+    /** Seq of the latest direct-user task message, or 0 before any. */
+    lastTaskSeq: number;
+    /** The discipline fold (spec, red/green color, green gate, pending pairs). */
+    discipline: DisciplineState;
+    /** A grill reminder is already on record in the log (durable `remindOnce`). */
+    grillReminded: boolean;
+    /** A red-gate reminder is already on record in the log (durable `remindOnce`). */
+    redReminded: boolean;
+    /** A green-gate reminder is already on record in the log (durable `remindOnce`). */
+    greenReminded: boolean;
+    /** A delivery-report reminder is already on record in the log (durable `remindOnce`). */
+    reportReminded: boolean;
+    /** Seq of the latest `doublecheck-review` source record, or -1 before any. */
+    lastReviewSeq: number;
+    /** Implementation edits folded after {@link lastReviewSeq}. */
+    editsAfterReview: number;
+}
+/**
+ * Install the guard listeners.
+ * @param ctx - plugin context; listeners unwind with it.
+ * @param config - validated {@link Config}; reserved-module misuse fails loud here.
+ */
+export declare function apply(ctx: Context, config: Config): void;