dsh-context-memory 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- **Remember** — append-only `.memory/events.jsonl`; every memory carries provenance
+  (session, step, author) so the question "why does the agent think it knows this" has
+  an answer.
+- **Recall** — relevance-ranked retrieval (token overlap, recency, verification
+  strength) instead of dumping every stored memory into context.
+- **Forget with a reason** — a memory is superseded, never silently deleted, and the
+  supersede event keeps the reason on the record.
+- **Conflict detection** — two active memories about the same subject are reported as a
+  conflict; the plugin does not pick a winner for you.
+- **Verification** — a checkable memory is compiled into a platform-aware guard and
+  re-checked on demand. `dsh-context-memory verify` exits non-zero only for a memory
+  whose guard ran and failed; a guard that cannot run is reported separately and is
+  never counted as a broken memory.
+- **Panel** — a `Context memory` settings page listing memory, verification status,
+  conflicts, and provenance.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hj01857655
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# dsh-context-memory
+
+[![npm version](https://img.shields.io/npm/v/dsh-context-memory)](https://www.npmjs.com/package/dsh-context-memory) [![CI](https://github.com/hj01857655/dsh-context-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/hj01857655/dsh-context-memory/actions/workflows/ci.yml)
+
+Cross-session memory for your dsh agent — remembered, recalled, and re-verified instead of assumed.
+
+## Install
+
+```sh
+dsh plugin --profile web add dsh-context-memory
+```
+
+## What it does
+
+Every session with your agent starts from nothing. What you decided yesterday, which
+approach failed, the constraint you explained once — all of it is gone, and you explain
+it again.
+
+This plugin keeps it, and — unlike a note file — re-checks the parts that can be checked.
+
+- **Remember.** A memory carries provenance: which session, which step, whether it came
+  from you, the agent, or a plugin. "Why does the agent think it knows this" has an
+  answer.
+- **Recall.** Retrieval is ranked (token overlap, recency, verification strength) instead
+  of pasting every memory into the context window. Each hit reports the breakdown of its
+  score, so a ranking is never something you have to trust.
+- **Forget with a reason.** A memory is superseded, never deleted. The wrong memories are
+  the most valuable records in the log — they are the only thing that can explain a past
+  decision.
+- **Conflict detection.** Two active memories about the same subject are reported as a
+  conflict. The plugin does not pick a winner; the log does not say which one is right,
+  and guessing would be the unfounded assertion this plugin exists to remove.
+- **Verification.** A memory whose statement has a checkable shape is compiled into a
+  platform-aware guard and re-checked on demand. This is the part a notes file cannot do.
+
+## The point
+
+A memory is a claim about the world. Storing it makes it *available*; it does not make it
+*true*. Statements like "the file README.md exists" or "config.json contains pnpm" were
+true when you said them and stop being true quietly.
+
+So `verify` turns each checkable memory back into a check and runs it:
+
+```sh
+dsh-context-memory verify
+```
+
+```
+passed      4f2a9c1b8e30  the file package.json exists
+violated    7d1e0a55c9f2  the file README.md contains Installation
+uncheckable 2b8f31aa0456  we settled on pnpm because yarn hoisting broke the build
+broken      a91c4e77b0d3  the file scripts/release.sh exists
+
+passed 1, violated 1, broken 1, uncheckable 1
+```
+
+Four outcomes, and the distinction between them is the whole point:
+
+| Outcome | Meaning |
+|---|---|
+| `passed` | The check ran and the memory holds. |
+| `violated` | The check ran and the world disagrees with the memory. |
+| `broken` | The check itself could not run — a typo, a missing binary. **Not** evidence about the memory. |
+| `uncheckable` | No check could be compiled. The memory is still stored and recalled; it is just not verified. |
+
+`verify` exits non-zero **only** for `violated`. A broken guard is a defect in the check,
+and letting it turn a pipeline red is how a typo would get a true memory marked false —
+after which you learn to ignore the output.
+
+Nothing is ever marked as verified because it was stored, and a memory supplied by the
+agent is never executed as a command: guards come from templates that only ever
+interpolate quoted file paths and literal search strings.
+
+## CLI
+
+```sh
+dsh-context-memory remember "the file package.json exists"
+dsh-context-memory list
+dsh-context-memory recall "how do we install"
+dsh-context-memory conflicts
+dsh-context-memory forget 4f2a9c1b8e30 "moved to bun"
+dsh-context-memory verify        # exit 1 only on a real violation
+```
+
+## Panel
+
+A `Context memory` page inside Settings: active and superseded memories, verification
+status per memory, conflicts, and provenance. The host registers
+`GET /api/context-memory.panel` and rebuilds the payload from the log on every request,
+so the panel shows what is on disk rather than what was in memory at startup. A headless
+host has no web connection and simply skips the route.
+
+## Layout
+
+| Path | Role |
+|---|---|
+| `src/index.ts` | Host half — `apply(ctx)`, exposes the `contextMemory` service |
+| `src/memory.ts` | Fold the log, remember, supersede, conflicts, verify |
+| `src/store.ts` | Append-only `.memory/events.jsonl` |
+| `src/guard.ts` | Statement → platform-aware check; run it; classify pass / violated / broken |
+| `src/recall.ts` | Relevance ranking with an explainable score |
+| `src/identity.ts` | Id derived from the normalised subject, so repeats fold |
+| `src/cli.ts` / `src/bin.ts` | Command-line entry, usable without dsh |
+| `src/routes.ts` | Panel and verify routes on the host's web connection |
+| `src/client/view.tsx` | Browser half — pure rendering, statically tested in Node |
+| `src/client/index.tsx` | Browser half — fetch and settings registration |
+
+## Why the log is append-only
+
+Current state is always a fold over the events, recomputed on each read. The
+alternative — a mutable store — lets the last writer decide what was always true, and
+"what did the agent believe on Tuesday, and why" becomes unanswerable. The log is the
+evidence, so a torn trailing line after a crash is dropped (recoverable) while damage
+anywhere else is reported rather than skipped.
+
+## Develop
+
+```sh
+npm ci
+npm run typecheck
+npm run build
+npm test
+```
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# The host half loads through this patch. `insert` appends the plugin to the profile's
+# bundle graph; the id must be unique within the profile or the loader reports a
+# duplicate entry id and refuses to start.
+- insert:
+    - id: dsh-context-memory
+      name: 'dsh-context-memory'

package/lib/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/lib/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from './cli.js';
+process.exitCode = run(process.argv.slice(2));

package/lib/cli.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Command-line entry.
+ *
+ * The same modules the host uses, reachable without booting dsh — so what the plugin
+ * claims about a project can be checked independently, and `verify` can run in CI.
+ *
+ * @module context-memory/cli
+ */
+export declare function run(argv: string[]): number;

package/lib/cli.js

@@ -0,0 +1,128 @@
+/**
+ * Command-line entry.
+ *
+ * The same modules the host uses, reachable without booting dsh — so what the plugin
+ * claims about a project can be checked independently, and `verify` can run in CI.
+ *
+ * @module context-memory/cli
+ */
+import { parseArgs } from 'node:util';
+import { ContextMemory } from './memory.js';
+export function run(argv) {
+    const { positionals, values } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            subject: { type: 'string' },
+            kind: { type: 'string' },
+            source: { type: 'string' },
+        },
+    });
+    const memory = new ContextMemory(process.cwd());
+    const cmd = positionals[0] ?? 'list';
+    switch (cmd) {
+        case 'remember': {
+            const text = positionals.slice(1).join(' ');
+            if (text.trim().length === 0) {
+                console.log('Usage: dsh-context-memory remember "<statement>" [--subject <what it is about>]');
+                return 1;
+            }
+            // `--subject` is what makes a conflict expressible from the command line: two
+            // different statements about one thing stay separate records instead of folding.
+            const stored = memory.remember({
+                text,
+                ...(values['subject'] !== undefined ? { subject: String(values['subject']) } : {}),
+                ...(values['kind'] !== undefined ? { kind: String(values['kind']) } : {}),
+                ...(values['source'] !== undefined ? { source: String(values['source']) } : {}),
+            });
+            const guard = stored.guard ? ` (guard: ${stored.guard.command})` : ' (no check could be compiled)';
+            console.log(`Remembered ${stored.id}: ${stored.text}${guard}`);
+            // A memory with no executable check is recorded, and the caller is told plainly
+            // that nothing will verify it — rather than reporting a success that implies more.
+            return 0;
+        }
+        case 'list': {
+            const active = memory.active();
+            if (active.length === 0) {
+                console.log('No memories recorded.');
+                return 0;
+            }
+            for (const item of active) {
+                const mark = item.verification?.outcome === 'passed' ? '✓' : item.verification ? '✗' : '·';
+                console.log(`${mark} ${item.id}  ${item.text}`);
+            }
+            return 0;
+        }
+        case 'recall': {
+            const query = positionals.slice(1).join(' ');
+            if (query.trim().length === 0) {
+                console.log('Usage: dsh-context-memory recall "<query>"');
+                return 1;
+            }
+            const hits = memory.recall(query);
+            if (hits.length === 0) {
+                console.log('Nothing relevant is remembered.');
+                return 0;
+            }
+            for (const hit of hits) {
+                console.log(`${hit.score.toFixed(3)}  ${hit.memory.text}`);
+                console.log(`         ${hit.why}`);
+            }
+            return 0;
+        }
+        case 'forget': {
+            const id = positionals[1] ?? '';
+            const reason = positionals.slice(2).join(' ');
+            if (id.length === 0 || reason.trim().length === 0) {
+                console.log('Usage: dsh-context-memory forget <id> "<reason>"');
+                console.log('A reason is required: a superseded memory is kept as the record of why it stopped being true.');
+                return 1;
+            }
+            const ok = memory.forget(id, reason);
+            console.log(ok ? `Superseded ${id}: ${reason}` : `No memory with id ${id}`);
+            return ok ? 0 : 1;
+        }
+        case 'conflicts': {
+            const conflicts = memory.conflicts();
+            if (conflicts.length === 0) {
+                console.log('No conflicts.');
+                return 0;
+            }
+            for (const conflict of conflicts) {
+                console.log(`Subject: ${conflict.subject}`);
+                for (const item of conflict.memories)
+                    console.log(`  - ${item.id}: ${item.text}`);
+            }
+            // A conflict is a question for the user, not a failure of this command.
+            return 0;
+        }
+        case 'verify': {
+            const summary = memory.verify();
+            for (const result of summary.results) {
+                console.log(`${result.outcome.padEnd(11)} ${result.id}  ${result.text}`);
+                if (result.outcome === 'broken' && result.output.trim().length > 0) {
+                    console.log(`            the check could not run: ${result.output.trim().split('\n')[0]}`);
+                }
+            }
+            console.log(`\npassed ${summary.passed}, violated ${summary.violated}, broken ${summary.broken}, uncheckable ${summary.uncheckable}`);
+            if (summary.broken > 0) {
+                console.log('broken guards are a defect in the check, not a memory that is wrong — they do not fail this command');
+            }
+            return ContextMemory.exitCode(summary);
+        }
+        case 'help':
+        default:
+            console.log('Usage: dsh-context-memory <command>');
+            console.log('Commands:');
+            console.log('  remember "<statement>"        record a memory and compile a check if possible');
+            console.log('    --subject <what it is about>  make a later disagreeing statement a conflict');
+            console.log('    --kind <fact|decision|preference|pitfall>');
+            console.log('    --source <user|agent|plugin>');
+            console.log('  list                          active memories, with verification status');
+            console.log('  recall "<query>"              rank memories by relevance');
+            console.log('  forget <id> "<reason>"        retire a memory, keeping the reason');
+            console.log('  conflicts                     active memories that disagree');
+            console.log('  verify                        re-run every compiled check; exit 1 only on a real violation');
+            return 0;
+    }
+}

package/lib/client/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Browser half of dsh-context-memory — the registration shell.
+ *
+ * Declaring `inject` at module scope is required, not stylistic: without it the client
+ * loader cannot resolve the settings and connection services, and the half fails to
+ * register with an unhelpful error.
+ *
+ * @module context-memory/client
+ */
+export declare const inject: string[];
+export declare function apply(ctx: {
+    inject: (deps: string[], fn: (...services: unknown[]) => void) => void;
+}): void;

package/lib/client/index.js

@@ -0,0 +1,32 @@
+/**
+ * Browser half of dsh-context-memory — the registration shell.
+ *
+ * Declaring `inject` at module scope is required, not stylistic: without it the client
+ * loader cannot resolve the settings and connection services, and the half fails to
+ * register with an unhelpful error.
+ *
+ * @module context-memory/client
+ */
+import { renderPanel } from './view.js';
+export const inject = ['@deepseek-ai/dsh-client-ui-settings', '@deepseek-ai/dsh-client-connection'];
+export function apply(ctx) {
+    ctx.inject(inject, (settings, connection) => {
+        const s = settings;
+        const c = connection;
+        s.section('context-memory', {
+            title: 'Context memory',
+            render: async () => {
+                try {
+                    const res = await c.fetch('/api/context-memory.panel');
+                    const payload = await res.json();
+                    return renderPanel(payload);
+                }
+                catch (error) {
+                    // Say what failed rather than rendering an empty panel, which would read as
+                    // "nothing is remembered" — a different and wrong answer.
+                    return `<div class="context-memory-panel"><h2>Context memory</h2><p>Could not load memories: ${String(error)}</p></div>`;
+                }
+            },
+        });
+    });
+}

package/lib/client/view.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Browser half of dsh-context-memory — the view model.
+ *
+ * Rendering is kept here, separate from the fetch-and-register shell, so it can be
+ * statically rendered in Node during tests. The panel is a claim about what the agent
+ * remembers, so it is worth asserting on without a browser.
+ *
+ * @module context-memory/client/view
+ */
+import type { MemoryState, PanelPayload } from '../types.js';
+/**
+ * A memory's verification badge.
+ *
+ * Four states, not two, because "no check exists" and "the check could not run" are
+ * different answers from "the check failed" — collapsing them would report an
+ * unverifiable memory and a false one identically, which is the failure this plugin
+ * exists to avoid.
+ */
+export declare function verificationLabel(memory: MemoryState): string;
+export declare function renderPanel(payload: PanelPayload): string;

package/lib/client/view.js

@@ -0,0 +1,64 @@
+/**
+ * Browser half of dsh-context-memory — the view model.
+ *
+ * Rendering is kept here, separate from the fetch-and-register shell, so it can be
+ * statically rendered in Node during tests. The panel is a claim about what the agent
+ * remembers, so it is worth asserting on without a browser.
+ *
+ * @module context-memory/client/view
+ */
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+/**
+ * A memory's verification badge.
+ *
+ * Four states, not two, because "no check exists" and "the check could not run" are
+ * different answers from "the check failed" — collapsing them would report an
+ * unverifiable memory and a false one identically, which is the failure this plugin
+ * exists to avoid.
+ */
+export function verificationLabel(memory) {
+    if (!memory.guard)
+        return 'no check';
+    switch (memory.verification?.outcome) {
+        case 'passed': return 'checked, holds';
+        case 'violated': return 'checked, does not hold';
+        case 'broken': return 'check unusable';
+        default: return 'not yet checked';
+    }
+}
+function rows(memories) {
+    return memories
+        .map((memory) => {
+        const provenance = [
+            memory.source,
+            memory.sessionId ? `session ${memory.sessionId}` : null,
+            memory.step !== undefined ? `step ${memory.step}` : null,
+        ].filter(Boolean).join(' · ');
+        return `<tr><td><code>${escapeHtml(memory.id)}</code></td><td>${escapeHtml(memory.text)}</td><td>${escapeHtml(memory.kind)}</td><td>${escapeHtml(verificationLabel(memory))}</td><td>${escapeHtml(provenance)}</td></tr>`;
+    })
+        .join('');
+}
+export function renderPanel(payload) {
+    const { totals } = payload;
+    const summary = `<p class="memory-summary">${totals.active} active (${totals.verified} checked and holding, ${totals.unverified} not), ${totals.superseded} superseded, ${totals.withGuard} with a compiled check.</p>`;
+    const conflictBlock = payload.conflicts.length === 0
+        ? '<p>No conflicts.</p>'
+        : `<div class="memory-conflicts"><h3>Conflicts</h3><ul>${payload.conflicts
+            .map((conflict) => `<li><strong>${escapeHtml(conflict.subject)}</strong><ul>${conflict.memories
+            .map((memory) => `<li><code>${escapeHtml(memory.id)}</code> ${escapeHtml(memory.text)}</li>`)
+            .join('')}</ul></li>`)
+            .join('')}</ul></div>`;
+    const activeBlock = payload.active.length === 0
+        ? '<p>Nothing is remembered yet.</p>'
+        : `<table><thead><tr><th>Id</th><th>Memory</th><th>Kind</th><th>Status</th><th>From</th></tr></thead><tbody>${rows(payload.active)}</tbody></table>`;
+    const supersededBlock = payload.superseded.length === 0
+        ? ''
+        : `<details><summary>Superseded (${payload.superseded.length})</summary><table><thead><tr><th>Id</th><th>Memory</th><th>Kind</th><th>Status</th><th>From</th></tr></thead><tbody>${rows(payload.superseded)}</tbody></table></details>`;
+    return `<div class="context-memory-panel"><h2>Context memory</h2>${summary}${conflictBlock}<h3>Active</h3>${activeBlock}${supersededBlock}</div>`;
+}

package/lib/guard.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Guard compilation and execution for memories.
+ *
+ * A memory is a claim, and this module is what decides whether the claim still holds.
+ * It keeps the same distinction dsh-verdict does, for the same reason: **a check that
+ * cannot run is not a memory that is wrong.** Conflating them would mean a mistyped
+ * path in a guard marks a perfectly good memory as false, and the user learns to
+ * ignore the output.
+ *
+ * Recognition is narrow on purpose. Only statement shapes whose checkable predicate is
+ * unambiguous get a guard; everything else stays uncheckable and says so. Emitting an
+ * approximate command would produce a check that exits 0 while verifying nothing, and
+ * every later "verified" would be a lie.
+ *
+ * There is deliberately **no** shape that runs a command taken from memory text. A
+ * memory can be written by the agent itself, so treating its content as an executable
+ * command is an injection path — the templates below only ever interpolate quoted file
+ * paths and literal search strings.
+ *
+ * @module context-memory/guard
+ */
+import type { Guard, GuardOutcome } from './types.js';
+/**
+ * Compile a memory statement into an executable check.
+ *
+ * Commands are emitted for the platform in use. `process.platform` rather than a
+ * hardcoded POSIX spelling: `test -e` on Windows would leave every compiled memory
+ * permanently unrunnable, so verification would report on nothing while looking busy.
+ */
+export declare function compileGuard(text: string, platform?: NodeJS.Platform): Guard | undefined;
+/**
+ * Quote a string so a POSIX shell treats it as one literal argument.
+ *
+ * Single quotes make every character literal; the only character that cannot appear
+ * inside them is the quote itself, escaped by closing, escaping, and reopening.
+ */
+export declare function shellQuote(value: string): string;
+/**
+ * Run one guard to completion.
+ *
+ * `spawnSync` with a shell so compound commands work as written. No timeout: a guard
+ * that hangs is a hang, and killing it after N seconds would turn "slow" into an
+ * outcome that varies with machine load.
+ */
+export declare function runGuard(id: string, guard: Guard, cwd: string, now?: Date): {
+    id: string;
+    outcome: GuardOutcome;
+    exitCode: null;
+    output: string;
+    at: string;
+} | {
+    id: string;
+    outcome: GuardOutcome;
+    exitCode: number;
+    output: string;
+    at: string;
+};
+/**
+ * Classify an exit code into an outcome.
+ *
+ * Two conventions mean "the command does not exist": POSIX shells use 127, cmd.exe
+ * uses 9009. Both are recognised, along with the text shells print instead of a
+ * distinctive code when the failure happens inside the shell. Without this, a
+ * misspelled path would look like a memory being wrong about the world.
+ */
+export declare function classify(code: number, output?: string): GuardOutcome;

package/lib/guard.js

@@ -0,0 +1,139 @@
+/**
+ * Guard compilation and execution for memories.
+ *
+ * A memory is a claim, and this module is what decides whether the claim still holds.
+ * It keeps the same distinction dsh-verdict does, for the same reason: **a check that
+ * cannot run is not a memory that is wrong.** Conflating them would mean a mistyped
+ * path in a guard marks a perfectly good memory as false, and the user learns to
+ * ignore the output.
+ *
+ * Recognition is narrow on purpose. Only statement shapes whose checkable predicate is
+ * unambiguous get a guard; everything else stays uncheckable and says so. Emitting an
+ * approximate command would produce a check that exits 0 while verifying nothing, and
+ * every later "verified" would be a lie.
+ *
+ * There is deliberately **no** shape that runs a command taken from memory text. A
+ * memory can be written by the agent itself, so treating its content as an executable
+ * command is an injection path — the templates below only ever interpolate quoted file
+ * paths and literal search strings.
+ *
+ * @module context-memory/guard
+ */
+import { spawnSync } from 'node:child_process';
+/** Enough output to diagnose, small enough to keep inline in the event log. */
+const OUTPUT_LIMIT = 2000;
+/**
+ * Compile a memory statement into an executable check.
+ *
+ * Commands are emitted for the platform in use. `process.platform` rather than a
+ * hardcoded POSIX spelling: `test -e` on Windows would leave every compiled memory
+ * permanently unrunnable, so verification would report on nothing while looking busy.
+ */
+export function compileGuard(text, platform = process.platform) {
+    const normalized = text.trim().replace(/\s+/g, ' ');
+    const posix = platform !== 'win32';
+    const operand = (value) => (posix ? shellQuote(value) : `"${value.replace(/"/g, '\\"')}"`);
+    // "the file X must not contain Y" — checked before the positive form so that the
+    // negated sentence is never read as an assertion that Y is present.
+    const fileLacks = /^(?:the )?(?:file|path) `?([^\s`]+)`? (?:must not|should not|never) (?:contain|mention|include) `?([^\s`]+)`?$/i.exec(normalized);
+    if (fileLacks?.[1] && fileLacks[2]) {
+        const [file, needle] = [fileLacks[1], fileLacks[2]];
+        // A quote inside the operand cannot survive cmd.exe's own quoting layer; refusing
+        // beats emitting a command whose meaning differs from the sentence.
+        if (!posix && needle.includes('"'))
+            return undefined;
+        return {
+            command: posix
+                ? `! grep -qF ${shellQuote(needle)} ${shellQuote(file)}`
+                : `findstr /c:${operand(needle)} ${operand(file)} >nul 2>nul && exit 1`,
+            source: 'template',
+        };
+    }
+    // "the file X contains Y" / "X mentions Y"
+    const fileHas = /^(?:the )?(?:file|path) `?([^\s`]+)`? (?:contains|mentions|includes) `?([^\s`]+)`?$/i.exec(normalized);
+    if (fileHas?.[1] && fileHas[2]) {
+        const [file, needle] = [fileHas[1], fileHas[2]];
+        if (!posix && needle.includes('"'))
+            return undefined;
+        return {
+            command: posix
+                ? `grep -qF ${shellQuote(needle)} ${shellQuote(file)}`
+                : `findstr /c:${operand(needle)} ${operand(file)} >nul`,
+            source: 'template',
+        };
+    }
+    // "the file X exists" / "X exists" / "X is at <path>" is the same predicate.
+    const fileExists = /^(?:the )?(?:file|path) `?([^\s`]+)`? (?:exists|is present)$/i.exec(normalized)
+        ?? /^`?([^\s`]+)`? exists$/i.exec(normalized);
+    if (fileExists?.[1]) {
+        const target = operand(fileExists[1]);
+        return {
+            command: posix ? `test -f ${target}` : `cmd /c if not exist ${target} exit 1`,
+            source: 'template',
+        };
+    }
+    // "there is no file X" / "never commit X"
+    const fileAbsent = /^(?:there is no|there are no|no) (?:file )?`?([^\s`]+)`?$/i.exec(normalized)
+        ?? /^(?:never|do not|don't) (?:create|add|commit|write|touch) (?:the )?(?:file )?`?([^\s`]+)`?$/i.exec(normalized);
+    if (fileAbsent?.[1]) {
+        const target = operand(fileAbsent[1]);
+        return {
+            command: posix ? `! test -e ${target}` : `cmd /c if exist ${target} exit 1`,
+            source: 'template',
+        };
+    }
+    return undefined;
+}
+/**
+ * Quote a string so a POSIX shell treats it as one literal argument.
+ *
+ * Single quotes make every character literal; the only character that cannot appear
+ * inside them is the quote itself, escaped by closing, escaping, and reopening.
+ */
+export function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Run one guard to completion.
+ *
+ * `spawnSync` with a shell so compound commands work as written. No timeout: a guard
+ * that hangs is a hang, and killing it after N seconds would turn "slow" into an
+ * outcome that varies with machine load.
+ */
+export function runGuard(id, guard, cwd, now = new Date()) {
+    const at = now.toISOString();
+    let proc;
+    try {
+        proc = spawnSync(guard.command, { cwd, shell: true, encoding: 'utf8' });
+    }
+    catch (error) {
+        return { id, outcome: 'broken', exitCode: null, output: String(error), at };
+    }
+    const output = `${proc.stdout ?? ''}${proc.stderr ?? ''}`.slice(0, OUTPUT_LIMIT);
+    if (proc.error) {
+        return { id, outcome: 'broken', exitCode: null, output: `${output}${proc.error.message}`.slice(0, OUTPUT_LIMIT), at };
+    }
+    const code = proc.status;
+    if (code === null) {
+        return { id, outcome: 'broken', exitCode: null, output: output || 'terminated by signal', at };
+    }
+    return { id, outcome: classify(code, output), exitCode: code, output, at };
+}
+/**
+ * Classify an exit code into an outcome.
+ *
+ * Two conventions mean "the command does not exist": POSIX shells use 127, cmd.exe
+ * uses 9009. Both are recognised, along with the text shells print instead of a
+ * distinctive code when the failure happens inside the shell. Without this, a
+ * misspelled path would look like a memory being wrong about the world.
+ */
+export function classify(code, output = '') {
+    if (code === 0)
+        return 'passed';
+    if (code === 127 || code === 9009)
+        return 'broken';
+    if (/command not found|is not recognized|No such file or directory|cannot open/i.test(output)) {
+        return 'broken';
+    }
+    return 'violated';
+}