dsh-doublecheck 0.5.0

package/lib/domain/report.js

@@ -0,0 +1,266 @@
+/**
+ * The doublecheck report fold: consolidate the durable discipline evidence of
+ * one session into report facts, derive the delivery verdict, and render the
+ * model-facing report document.
+ *
+ * Everything here folds the session log alone — the spec (from the
+ * `doublecheck_spec` call arguments), the test-run timeline (red/green
+ * outcomes), the implementation edits, and the injected
+ * `doublecheck-review` source records — so a report re-derived after resume
+ * or fork reads identically.
+ *
+ * @module dsh-doublecheck/domain/report
+ */
+import { isTestCommand, isTestFilePath, joinTextBlocks, mutationTargetPath, parseRawArguments, shellCommand, testOutcome, } from "./evidence.js";
+import { SPEC_TOOL_NAME } from "./stages.js";
+import { VERIFY_DIMENSIONS, } from "./vocabulary.js";
+/** Maximum timeline rows rendered into the report document. */
+const TIMELINE_RENDER_CAP = 20;
+/** Empty facts: nothing evidenced yet. */
+export function emptyReportFacts() {
+    return { spec: null, testRuns: { failed: 0, passed: 0 }, timeline: [], edits: 0, review: null };
+}
+/**
+ * Fold a session log into report facts.
+ * @param events - the session's append-only event log.
+ * @param detection - the compiled test-run/mutation detection knobs.
+ * @returns the complete folded facts.
+ */
+export function foldReportFacts(events, detection) {
+    const facts = emptyReportFacts();
+    const pendingTests = new Map();
+    /** Spec calls awaiting a result: only a successful pair commits the spec. */
+    const pendingSpecs = new Map();
+    for (const event of events) {
+        switch (event.type) {
+            case 'tool/call': {
+                const args = parseRawArguments(event.data.arguments);
+                if (event.data.name === SPEC_TOOL_NAME) {
+                    const spec = readSpecFromArgs(args);
+                    if (spec !== null)
+                        pendingSpecs.set(event.data.callId, spec);
+                }
+                const command = shellCommand(event.data.name, args, detection);
+                if (command !== undefined && isTestCommand(command, detection)) {
+                    pendingTests.set(event.data.callId, command);
+                }
+                const path = mutationTargetPath(event.data.name, args, detection);
+                if (path !== undefined && !isTestFilePath(path, detection)) {
+                    facts.edits += 1;
+                }
+                break;
+            }
+            case 'tool/result': {
+                const callId = event.data.message.source.callId;
+                const spec = pendingSpecs.get(callId);
+                if (spec !== undefined && event.data.error === undefined) {
+                    pendingSpecs.delete(callId);
+                    facts.spec = spec;
+                    facts.timeline.push({ kind: 'spec', detail: preview(spec.goal) });
+                }
+                else if (spec !== undefined) {
+                    pendingSpecs.delete(callId);
+                }
+                const command = pendingTests.get(callId);
+                if (command === undefined)
+                    break;
+                pendingTests.delete(callId);
+                foldTestRun(facts, command, testOutcome(joinTextBlocks(event.data.message.content), event.data.error !== undefined));
+                break;
+            }
+            case 'tool/code-dispatch': {
+                const args = parseRawArguments(event.data.arguments);
+                const command = shellCommand(event.data.name, args, detection);
+                if (command !== undefined && isTestCommand(command, detection)) {
+                    foldTestRun(facts, command, testOutcome(joinTextBlocks(event.data.content), event.data.isError));
+                }
+                // Code Mode dispatches run through the same pre-execute policy gates,
+                // so a dispatched edit is a real implementation edit and must count
+                // toward the report exactly like a native call.
+                const path = mutationTargetPath(event.data.name, args, detection);
+                if (path !== undefined && !isTestFilePath(path, detection)) {
+                    facts.edits += 1;
+                }
+                break;
+            }
+            case 'user/message': {
+                const source = event.data.source;
+                if (source.kind !== 'doublecheck-review')
+                    break;
+                const record = source;
+                facts.review = { verdict: record.verdict, findings: [...record.findings] };
+                facts.timeline.push({ kind: 'review', detail: record.verdict });
+                break;
+            }
+        }
+    }
+    return facts;
+}
+/** Fold one settled test-run outcome into the counts and timeline. */
+function foldTestRun(facts, command, outcome) {
+    if (outcome === 'fail') {
+        facts.testRuns.failed += 1;
+        facts.timeline.push({ kind: 'red', detail: preview(command) });
+    }
+    else if (outcome === 'pass') {
+        facts.testRuns.passed += 1;
+        facts.timeline.push({ kind: 'green', detail: preview(command) });
+    }
+}
+/** Read the six spec fields from a spec tool call's arguments, or null when malformed. */
+function readSpecFromArgs(args) {
+    if (args === undefined)
+        return null;
+    const { goal, scope, acceptanceCriteria, failureModes, priorities, nonGoals } = args;
+    if (typeof goal !== 'string' || typeof scope !== 'string' || typeof acceptanceCriteria !== 'string'
+        || typeof failureModes !== 'string' || typeof priorities !== 'string' || typeof nonGoals !== 'string') {
+        return null;
+    }
+    return { goal, scope, acceptanceCriteria, failureModes, priorities, nonGoals };
+}
+/**
+ * Derive the delivery verdict from the folded facts, the optional review,
+ * and the optional verification outcome.
+ * @param facts - the folded session facts.
+ * @param verification - verification outcome when the verify workflow ran, else null.
+ * @returns the report verdict.
+ */
+export function deriveReportVerdict(facts, verification) {
+    if (facts.spec === null)
+        return 'grill';
+    if (facts.edits === 0)
+        return 'draft';
+    const lastTest = facts.timeline.findLast(entry => entry.kind === 'red' || entry.kind === 'green');
+    if (lastTest?.kind === 'red')
+        return 'red';
+    if (verification !== null) {
+        if (verification.checks.some(check => check.verdict === 'fail'))
+            return 'challenged';
+        // A missing dimension is not a pass: `proven` requires a verdict for
+        // every spec dimension.
+        return verification.complete ? 'proven' : 'unverified';
+    }
+    if (facts.review === null || facts.review.verdict === 'unavailable')
+        return 'green';
+    return facts.review.verdict === 'findings' ? 'objections' : 'verified';
+}
+/** Render the report facts as the model-facing markdown document. */
+export function renderReportMarkdown(data) {
+    const lines = [
+        '# Doublecheck report',
+        '',
+        `> Verdict: **${data.verdict}**`,
+        '',
+        '## Spec',
+    ];
+    if (data.spec === null) {
+        lines.push('No spec recorded; the requirements grill has not committed anything yet.', '');
+    }
+    else {
+        lines.push(`- Goal: ${data.spec.goal}`, `- Scope: ${data.spec.scope}`, `- Acceptance criteria: ${data.spec.acceptanceCriteria}`, `- Failure modes: ${data.spec.failureModes}`, `- Priorities: ${data.spec.priorities}`, `- Non-goals: ${data.spec.nonGoals}`, '');
+    }
+    lines.push('## Test evidence', `- failing runs: ${data.testRuns.failed}`, `- passing runs: ${data.testRuns.passed}`, '');
+    const rows = data.timeline.slice(-TIMELINE_RENDER_CAP);
+    lines.push(...rows.map(row => `- [${row.kind}] ${row.detail}`));
+    if (data.timeline.length > rows.length) {
+        lines.push(`- … ${data.timeline.length - rows.length} earlier rows omitted`);
+    }
+    lines.push('', '## Adversary review');
+    if (data.review === null) {
+        lines.push('No adversary review ran for this session.');
+    }
+    else if (data.review.verdict === 'findings') {
+        lines.push(...data.review.findings.map(finding => `- [${finding.severity}] ${finding.title} — ${finding.detail}`));
+    }
+    else {
+        lines.push(`Verdict: ${data.review.verdict}`);
+    }
+    lines.push('', '## Verification');
+    if (data.verification === null) {
+        lines.push('Not run.');
+    }
+    else {
+        for (const check of data.verification.checks) {
+            lines.push(`- [${check.verdict}] ${check.dimension}: ${check.evidence} ${check.note.length > 0 ? `(${check.note})` : ''}`.trim());
+        }
+        if (!data.verification.complete) {
+            lines.push(`- … not every spec dimension returned a verdict; the delivery is not proven.`);
+        }
+    }
+    lines.push('', `## Delivery`, `- implementation edits: ${data.edits}`, '');
+    return lines.join('\n');
+}
+/** The structured output each verification child must satisfy. */
+export const VERIFY_CHECK_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['dimension', 'verdict', 'evidence', 'note'],
+    properties: {
+        dimension: { type: 'string', enum: [...VERIFY_DIMENSIONS] },
+        verdict: { type: 'string', enum: ['pass', 'fail'] },
+        evidence: { type: 'string' },
+        note: { type: 'string' },
+    },
+};
+/** The verify workflow identity block. */
+export const VERIFY_META = {
+    name: 'doublecheck-verify',
+    description: 'Verify a doublecheck delivery across the six spec dimensions and return one check per dimension.',
+    phases: [{ title: 'doublecheck verify' }],
+};
+/**
+ * The single-checker structured output: one agent auditing every spec
+ * dimension and returning a check per dimension. Mirrors the parallel
+ * mode's `{ checks: [...] }` result shape so the fold is identical.
+ */
+const VERIFY_BATCH_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['checks'],
+    properties: {
+        checks: { type: 'array', items: VERIFY_CHECK_SCHEMA },
+    },
+};
+/**
+ * Build the verify workflow script body.
+ * @param mode - `all` fans out one parallel checker per spec dimension;
+ * `single` runs one checker over every dimension (cheaper, one subagent).
+ * @returns the plain-JS script body for `WorkflowStartRequest.script`.
+ */
+export function buildVerifyScript(mode) {
+    if (mode === 'single') {
+        return [
+            "phase('doublecheck verify')",
+            'const checks = await agent(',
+            "  'You verify every dimension of a requirements spec against the session you inherited. "
+                + "The spec: ' + JSON.stringify(args.spec) + '. "
+                + 'Assume the delivery FAILS each dimension. Examine the inherited session for evidence: '
+                + 'the recorded spec, the red/green test runs, the edits, and any review findings. '
+                + 'Answer through the required structured output: one check per dimension; pass only when the session evidence '
+                + 'satisfies that dimension, fail otherwise, with evidence cited from the session '
+                + "and a note on what to fix.',",
+            '  { label: \'verify-all\', schema: ' + JSON.stringify(VERIFY_BATCH_SCHEMA) + ' })',
+            'return { checks: checks.checks.filter(Boolean) }',
+        ].join('\n');
+    }
+    return [
+        "phase('doublecheck verify')",
+        'const checks = await parallel(args.dimensions.map(function (dimension) {',
+        '  return function () {',
+        "    return agent('You verify one dimension of a requirements spec against the session you inherited. "
+            + "The dimension: ' + dimension + '. The spec says: ' + args.spec[dimension] + '. "
+            + "Assume the delivery FAILS this dimension. Examine the inherited session for evidence: "
+            + "the recorded spec, the red/green test runs, the edits, and any review findings. "
+            + "Answer through the required structured output: pass only when the session evidence "
+            + "satisfies the dimension; fail otherwise, with evidence cited from the session "
+            + "and a note on what to fix.',",
+        `    { label: 'verify-' + dimension, schema: ${JSON.stringify(VERIFY_CHECK_SCHEMA)} })`,
+        '  }',
+        '}))',
+        'return { checks: checks.filter(Boolean) }',
+    ].join('\n');
+}
+/** Truncate a spec goal for timeline rows. */
+function preview(text) {
+    return text.length > 120 ? `${text.slice(0, 120)}…` : text;
+}

package/lib/domain/stages.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The dsh-doublecheck discipline state machine.
+ *
+ * Six stages: `grill` (settle requirements) → `design` (spec committed) →
+ * `red` (failing test) → `green` (passing test) → `review` (self-review) →
+ * `verify` (delivery proof). v0.1 implemented the first transition; v0.2 adds
+ * the red/green evidence transitions folded from durable test-run records.
+ *
+ * The state derives from the session log, never from process memory: a
+ * `doublecheck_spec` call with a successful result advances past `grill`, a
+ * failing test run marks `red`, a passing run marks `green`, and any
+ * implementation edit after the latest passing run re-arms the green gate.
+ * Resumed and forked sessions fold to the same state as the live run.
+ *
+ * @module dsh-doublecheck/domain/stages
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import { type TestRunDetection } from './evidence.ts';
+/** The discipline stages, in execution order. */
+export type DisciplineStage = 'grill' | 'design' | 'red' | 'green' | 'review' | 'verify';
+/** All discipline stages in order. */
+export declare const DISCIPLINE_STAGES: readonly DisciplineStage[];
+/** Name of the model-facing tool that commits a grilled requirements spec. */
+export declare const SPEC_TOOL_NAME = "doublecheck_spec";
+/** Name of the model-facing tool that consolidates the delivery report. */
+export declare const REPORT_TOOL_NAME = "doublecheck_report";
+/** The current red/green color of the session: the latest test-run evidence. */
+export type TestColor = 'none' | 'red' | 'green';
+/**
+ * The folded discipline facts for one session log. The `pending*` sets are
+ * fold bookkeeping: calls whose results have not been folded yet, carried
+ * across incremental fold batches.
+ */
+export interface DisciplineState {
+    /** The last stage a successful discipline call or test run reached. */
+    stage: DisciplineStage;
+    /** Whether a successful `doublecheck_spec` call exists in the log. */
+    hasSpec: boolean;
+    /** The log sequence of the latest successful spec commit (0 = none). Guards compare it with the latest direct user task to reopen the grill on new tasks. */
+    specSeq: number;
+    /** The latest test-run evidence: red = failing since the last pass. */
+    color: TestColor;
+    /** An implementation edit happened after the latest passing test run. */
+    pendingGreen: boolean;
+    /** Total implementation edits folded so far (the green-gate reminder epoch). */
+    editCount: number;
+    /** Stage-tool call ids whose results have not been folded yet, mapped to the stage they advance. */
+    pendingStageCalls: Map<string, DisciplineStage>;
+    /** Test-run call ids whose results have not been folded yet. */
+    pendingTestCalls: Set<string>;
+}
+/** A fresh fold state: nothing evidenced yet. */
+export declare function emptyDisciplineState(): DisciplineState;
+/**
+ * Call ids of successful invocations of `toolName` in the given event log. A
+ * call is successful when some `tool/result` pairs with its `callId` and
+ * carries no error record. One pass over the log: results always follow
+ * their calls, so a pending call set pairs them in place.
+ * @param events - the session's append-only event log.
+ * @param toolName - the tool whose successful calls are collected.
+ * @returns every successful call id, in log order.
+ */
+export declare function successfulToolCalls(events: readonly SessionEvent[], toolName: string): string[];
+/**
+ * Fold `events[start..end)` into the discipline state. Each event is folded
+ * once; the state's pending sets carry unmatched calls across batches, so the
+ * caller can advance an existing state over the newly appended tail instead
+ * of refolding the whole log.
+ * @param state - the state to advance (start one via {@link emptyDisciplineState}).
+ * @param events - the session's append-only event log.
+ * @param start - first index to fold.
+ * @param detection - the compiled red/green evidence knobs.
+ * @returns the same state instance, advanced.
+ */
+export declare function foldDisciplineRange(state: DisciplineState, events: readonly SessionEvent[], start: number, detection: TestRunDetection): DisciplineState;
+/**
+ * Fold a session log from scratch to its current discipline state.
+ * @param events - the session's append-only event log.
+ * @param detection - the compiled red/green evidence knobs; omit to ignore test runs.
+ * @returns the complete folded state.
+ */
+export declare function foldDisciplineState(events: readonly SessionEvent[], detection?: TestRunDetection): DisciplineState;
+/**
+ * Fold a session log to its current discipline stage. Only successful calls
+ * and real test runs advance the stage; a failed spec attempt leaves the
+ * session in `grill`, and red/green move with the latest test evidence.
+ * @param events - the session's append-only event log.
+ * @param detection - the compiled red/green evidence knobs; omit to ignore test runs.
+ * @returns the last stage reached, or `grill`.
+ */
+export declare function foldDisciplineStage(events: readonly SessionEvent[], detection?: TestRunDetection): DisciplineStage;
+/**
+ * Whether the session's requirements grill has produced a committed spec.
+ * @param events - the session's append-only event log.
+ * @returns true when a successful `doublecheck_spec` call exists in the log;
+ * the scan stops at the first successful pair it finds.
+ */
+export declare function sessionHasSpec(events: readonly SessionEvent[]): boolean;

package/lib/domain/stages.js

@@ -0,0 +1,192 @@
+/**
+ * The dsh-doublecheck discipline state machine.
+ *
+ * Six stages: `grill` (settle requirements) → `design` (spec committed) →
+ * `red` (failing test) → `green` (passing test) → `review` (self-review) →
+ * `verify` (delivery proof). v0.1 implemented the first transition; v0.2 adds
+ * the red/green evidence transitions folded from durable test-run records.
+ *
+ * The state derives from the session log, never from process memory: a
+ * `doublecheck_spec` call with a successful result advances past `grill`, a
+ * failing test run marks `red`, a passing run marks `green`, and any
+ * implementation edit after the latest passing run re-arms the green gate.
+ * Resumed and forked sessions fold to the same state as the live run.
+ *
+ * @module dsh-doublecheck/domain/stages
+ */
+import { emptyDetection, isTestCommand, isTestFilePath, joinTextBlocks, mutationTargetPath, parseRawArguments, shellCommand, testOutcome, } from "./evidence.js";
+/** All discipline stages in order. */
+export const DISCIPLINE_STAGES = [
+    'grill', 'design', 'red', 'green', 'review', 'verify',
+];
+/** Name of the model-facing tool that commits a grilled requirements spec. */
+export const SPEC_TOOL_NAME = 'doublecheck_spec';
+/** Name of the model-facing tool that consolidates the delivery report. */
+export const REPORT_TOOL_NAME = 'doublecheck_report';
+/** Which stage a successful call of the named tool advances the session to. */
+const STAGE_BY_TOOL = {
+    [SPEC_TOOL_NAME]: 'design',
+    [REPORT_TOOL_NAME]: 'verify',
+};
+/** A fresh fold state: nothing evidenced yet. */
+export function emptyDisciplineState() {
+    return {
+        stage: 'grill',
+        hasSpec: false,
+        specSeq: 0,
+        color: 'none',
+        pendingGreen: false,
+        editCount: 0,
+        pendingStageCalls: new Map(),
+        pendingTestCalls: new Set(),
+    };
+}
+/**
+ * Call ids of successful invocations of `toolName` in the given event log. A
+ * call is successful when some `tool/result` pairs with its `callId` and
+ * carries no error record. One pass over the log: results always follow
+ * their calls, so a pending call set pairs them in place.
+ * @param events - the session's append-only event log.
+ * @param toolName - the tool whose successful calls are collected.
+ * @returns every successful call id, in log order.
+ */
+export function successfulToolCalls(events, toolName) {
+    const pending = new Set();
+    const succeeded = [];
+    for (const event of events) {
+        if (event.type === 'tool/call') {
+            if (event.data.name === toolName)
+                pending.add(event.data.callId);
+        }
+        else if (event.type === 'tool/result') {
+            const callId = event.data.message.source.callId;
+            if (event.data.error === undefined && pending.delete(callId))
+                succeeded.push(callId);
+        }
+    }
+    return succeeded;
+}
+/**
+ * Fold `events[start..end)` into the discipline state. Each event is folded
+ * once; the state's pending sets carry unmatched calls across batches, so the
+ * caller can advance an existing state over the newly appended tail instead
+ * of refolding the whole log.
+ * @param state - the state to advance (start one via {@link emptyDisciplineState}).
+ * @param events - the session's append-only event log.
+ * @param start - first index to fold.
+ * @param detection - the compiled red/green evidence knobs.
+ * @returns the same state instance, advanced.
+ */
+export function foldDisciplineRange(state, events, start, detection) {
+    for (let index = start; index < events.length; index += 1) {
+        const event = events[index];
+        if (event === undefined)
+            continue;
+        switch (event.type) {
+            case 'tool/call': {
+                const args = parseRawArguments(event.data.arguments);
+                const stage = STAGE_BY_TOOL[event.data.name];
+                if (stage !== undefined) {
+                    state.pendingStageCalls.set(event.data.callId, stage);
+                }
+                const command = shellCommand(event.data.name, args, detection);
+                if (command !== undefined && isTestCommand(command, detection)) {
+                    state.pendingTestCalls.add(event.data.callId);
+                }
+                const path = mutationTargetPath(event.data.name, args, detection);
+                if (path !== undefined && !isTestFilePath(path, detection)) {
+                    state.pendingGreen = true;
+                    state.editCount += 1;
+                }
+                break;
+            }
+            case 'tool/result': {
+                const callId = event.data.message.source.callId;
+                const stage = state.pendingStageCalls.get(callId);
+                if (stage !== undefined) {
+                    state.pendingStageCalls.delete(callId);
+                    if (event.data.error === undefined) {
+                        if (stage === 'design') {
+                            state.hasSpec = true;
+                            state.specSeq = event.seq;
+                        }
+                        state.stage = stage;
+                    }
+                }
+                if (state.pendingTestCalls.delete(callId)) {
+                    foldTestOutcome(state, testOutcome(joinTextBlocks(event.data.message.content), event.data.error !== undefined));
+                }
+                break;
+            }
+            case 'tool/code-dispatch': {
+                const args = parseRawArguments(event.data.arguments);
+                const command = shellCommand(event.data.name, args, detection);
+                if (command !== undefined && isTestCommand(command, detection)) {
+                    foldTestOutcome(state, testOutcome(joinTextBlocks(event.data.content), event.data.isError));
+                }
+                // Code Mode dispatches run through the same pre-execute policy gates,
+                // so a dispatched edit is a real implementation edit and must count
+                // toward the green gate and the report exactly like a native call.
+                const path = mutationTargetPath(event.data.name, args, detection);
+                if (path !== undefined && !isTestFilePath(path, detection)) {
+                    state.pendingGreen = true;
+                    state.editCount += 1;
+                }
+                break;
+            }
+        }
+    }
+    return state;
+}
+/** Apply one test-run outcome to the color and the green gate. */
+function foldTestOutcome(state, outcome) {
+    if (outcome === 'fail') {
+        state.color = 'red';
+        state.stage = 'red';
+    }
+    else if (outcome === 'pass') {
+        state.color = 'green';
+        state.stage = 'green';
+        state.pendingGreen = false;
+    }
+}
+/**
+ * Fold a session log from scratch to its current discipline state.
+ * @param events - the session's append-only event log.
+ * @param detection - the compiled red/green evidence knobs; omit to ignore test runs.
+ * @returns the complete folded state.
+ */
+export function foldDisciplineState(events, detection = emptyDetection()) {
+    return foldDisciplineRange(emptyDisciplineState(), events, 0, detection);
+}
+/**
+ * Fold a session log to its current discipline stage. Only successful calls
+ * and real test runs advance the stage; a failed spec attempt leaves the
+ * session in `grill`, and red/green move with the latest test evidence.
+ * @param events - the session's append-only event log.
+ * @param detection - the compiled red/green evidence knobs; omit to ignore test runs.
+ * @returns the last stage reached, or `grill`.
+ */
+export function foldDisciplineStage(events, detection = emptyDetection()) {
+    return foldDisciplineState(events, detection).stage;
+}
+/**
+ * Whether the session's requirements grill has produced a committed spec.
+ * @param events - the session's append-only event log.
+ * @returns true when a successful `doublecheck_spec` call exists in the log;
+ * the scan stops at the first successful pair it finds.
+ */
+export function sessionHasSpec(events) {
+    const pending = new Set();
+    for (const event of events) {
+        if (event.type === 'tool/call') {
+            if (event.data.name === SPEC_TOOL_NAME)
+                pending.add(event.data.callId);
+        }
+        else if (event.type === 'tool/result') {
+            if (event.data.error === undefined && pending.delete(event.data.message.source.callId))
+                return true;
+        }
+    }
+    return false;
+}

package/lib/domain/vagueness.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Task-vagueness detection for the discipline guard.
+ *
+ * A task is "vague" when it is brief and names no concrete artifact. Brief is
+ * a deployment knob (`vagueTaskMaxChars`); artifact detection is a fixed
+ * structural test: a file extension token, a drive-letter prefix, a
+ * path-separator token, a quoted keyword, an underscore keyword, or a
+ * hyphenated keyword. A task that names an artifact (or a URL) is concrete
+ * enough to edit without a grill even when it is short; a long task is
+ * assumed to carry its own requirements.
+ *
+ * @module dsh-doublecheck/domain/vagueness
+ */
+/** The tunable part of the vagueness test. */
+export interface VaguenessConfig {
+    /** Task text longer than this many characters is never considered vague. */
+    vagueTaskMaxChars: number;
+}
+/**
+ * Decide whether a user task statement needs a requirements grill.
+ * @param text - the task text as given by the user.
+ * @param config - the vagueness tuning.
+ * @returns true when the task is brief and names no concrete artifact.
+ */
+export declare function isVagueTask(text: string, config: VaguenessConfig): boolean;

package/lib/domain/vagueness.js

@@ -0,0 +1,56 @@
+/**
+ * Task-vagueness detection for the discipline guard.
+ *
+ * A task is "vague" when it is brief and names no concrete artifact. Brief is
+ * a deployment knob (`vagueTaskMaxChars`); artifact detection is a fixed
+ * structural test: a file extension token, a drive-letter prefix, a
+ * path-separator token, a quoted keyword, an underscore keyword, or a
+ * hyphenated keyword. A task that names an artifact (or a URL) is concrete
+ * enough to edit without a grill even when it is short; a long task is
+ * assumed to carry its own requirements.
+ *
+ * @module dsh-doublecheck/domain/vagueness
+ */
+/** Extension token, Windows drive prefix, or a leading path separator followed by a path body. */
+const ARTIFACT_HINT = /(?:\.[A-Za-z][\w-]{0,10}(?:$|[\s"'`.,:;)\]])|[A-Za-z]:[\\/]|[\\/][^\s"'`]+)/;
+/**
+ * A quoted keyword such as `"foo"`, `'bar'`, `` `baz` ``, “关键词” or 「关键词」.
+ * Requires at least one non-whitespace character between the quotes so an
+ * empty pair like `""` does not make a task concrete.
+ */
+const QUOTED_HINT = /["'`“”「」『』][^"'`“”「」『』]*\S[^"'`“”「」『』]*["'`“”「」『』]/;
+/**
+ * An identifier-style keyword containing an underscore, such as `retry_limit`
+ * or `user_name`. Prose rarely uses underscores, so their presence signals a
+ * concrete name (a variable, config key, or function) rather than a vague
+ * wish. Requires an alphanumeric character at each end so a bare separator
+ * (`_`), a pure underscore run (`___`), or a trailing `thing_` does not count.
+ */
+const UNDERSCORE_KEYWORD = /[A-Za-z0-9][A-Za-z0-9_]*_[A-Za-z0-9_]*[A-Za-z0-9]/;
+/**
+ * An identifier-style keyword containing a hyphen, such as `retry-limit`,
+ * `user-name`, or a CLI flag like `--verbose=false`'s `verbose`. Mirrors
+ * `UNDERSCORE_KEYWORD`: it requires an alphanumeric character at each end so
+ * a bare separator (`-`), a pure hyphen run (`---`), a leading `-foo`, or a
+ * trailing `thing-` does not count. Ordinary hyphenated compounds
+ * (e.g. `well-known`), dates, and numeric ranges also match; that is the
+ * accepted cost of recognizing config keys and option names.
+ */
+const HYPHENATED_KEYWORD = /[A-Za-z0-9][A-Za-z0-9-]*-[A-Za-z0-9-]*[A-Za-z0-9]/;
+/**
+ * Decide whether a user task statement needs a requirements grill.
+ * @param text - the task text as given by the user.
+ * @param config - the vagueness tuning.
+ * @returns true when the task is brief and names no concrete artifact.
+ */
+export function isVagueTask(text, config) {
+    const normalized = text.trim();
+    if (normalized.length === 0)
+        return false;
+    if (normalized.length > config.vagueTaskMaxChars)
+        return false;
+    return !(ARTIFACT_HINT.test(normalized) ||
+        QUOTED_HINT.test(normalized) ||
+        UNDERSCORE_KEYWORD.test(normalized) ||
+        HYPHENATED_KEYWORD.test(normalized));
+}