@nurix/etna 0.19.42 → 0.19.43

package/data/harnesses/apollo/skills/brainstorm/references/session-schema.md

@@ -0,0 +1,186 @@
+# Session schema — the single format authority
+
+Load when: bootstrapping a session, writing any working-surface file, dispatching the twin, or
+interpreting detector output. The detector (`scripts/detector.mjs`) is the mechanical half of this
+contract — every rule below that carries a rule ID is machine-checked; everything else is the
+twin's semantic judgment.
+
+## Folder layout
+
+```
+docs/research/{topic}-brainstorm/     ← open session (kebab-case topic slug)
+├── state.md                          ← anchor + aspect map (twin-written)
+├── thesis.md                         ← composed claim → argument → what changed (twin-written)
+├── forks.md                          ← open questions with close conditions (twin-written)
+├── ledger.md                         ← commitments (twin-written)
+├── basis/                            ← frozen entry material (facilitator-written once, at intake)
+├── fragments/                        ← harvest-native fragments (twin-written; materialize on
+│                                        first real content, drafted in destination format)
+└── ops/                              ← untracked capture layer (deleted at stop)
+    ├── .gitignore                    ← contains `*` — ops/ never enters git      [BS-OPS-01/02]
+    ├── capture.md                    ← facilitator's raw append ledger (its ONLY write)
+    ├── sync-log.md                   ← paired twin-dispatch log
+    └── manifest.md                   ← harvest manifest (created by the stop pipeline)
+```
+
+On a passed harvest the folder **moves** to `docs/history/brainstorms/{topic}/` (ops/ deleted
+first) — the move is the completion marker; the user then deletes or commits it. A folder still
+under `docs/research/` is by definition unfinished.
+
+**Write protocol (one writer per file):** the facilitator appends to `ops/capture.md` and writes
+the initial `basis/` copy plus the sync-log *dispatch* lines — nothing else, ever. The twin writes
+every other file, at gates. The user may hand-edit anything; the twin diffs each file against its
+own last compose before rewriting and folds foreign edits as first-class user signal.
+
+## state.md
+
+```markdown
+# State
+
+- Status: open | stopping | harvested
+- Posture: mid-probe on the sync-layer aspect, three forks open
+- Started: 2026-07-08
+- Sitting: single | multi
+- Last compose: 2026-07-08T14:30Z | never
+
+## Aspect map
+
+- persistence — how session state survives restarts → F1, D3
+- onboarding — the first-run experience → thesis
+- risks — failure modes and mitigations → none yet
+```
+
+- `Status` transitions only forward: `open → stopping → harvested` (the twin flips `stopping` when
+  the stop pipeline begins, `harvested` at the move). [BS-STATE-01]
+- The aspect map is derived per idea from the basis and edited by the user. Each aspect carries
+  `→` refs to the content covering it: fork IDs (`F#`), ledger IDs (`D#`), `thesis`,
+  `fragment:{name}`, or `none yet` (an open coverage gap — informational mid-session
+  [BS-ASPECT-01], blocking at the manifest gate [BS-ASPECT-02]). Ref *presence* is the detector's
+  half; whether the content actually covers the aspect is the twin's.
+
+## thesis.md
+
+```markdown
+# {Topic} — thesis
+
+Current as of: 2026-07-08T14:30Z
+
+## Claim
+## Argument
+## What changed
+```
+
+Composed prose, rewritten whole at every compose, never appended. The three sections and the
+stamp are mandatory [BS-THESIS-01]; the stamp must equal state.md's `Last compose`
+[BS-COMPOSE-01]. At the manifest gate, `Last compose` must be later than the newest
+`ops/capture.md` entry — a compose over unsynced capture is stale [BS-COMPOSE-02].
+
+## forks.md
+
+```markdown
+## F3 — Should reads wait for a compose? [open]
+
+Full self-contained prose in the user's framing.
+
+- Raised by: user | twin (S4) | probe | harvest
+- Closes when: a pick between wait-for-fresh and read-stale-with-warning
+```
+
+- IDs `F1, F2, …` unique, never reused [BS-FORK-01]. Status marker: `[open]` or
+  `[parked → {destination}]`. Every fork carries `Closes when:` [BS-FORK-01].
+- `Raised by: twin (S#)` must cite a reconciled sync-log entry [BS-SYNC-02].
+- **A resolved fork's entry is deleted** by the twin — the resolving ledger entry's `Resolves:`
+  field is the record. forks.md holds only open and parked forks; a ledger `Resolves: F3`
+  coexisting with an open F3 is an inconsistency [BS-FORK-02]. Parked forks survive to the
+  manifest, which must route each one [BS-MANIFEST-01].
+- The manifest gate requires zero `[open]` forks [BS-FORK-03].
+
+## ledger.md
+
+```markdown
+## D4 — Sessions initialize in dump or interview
+
+- Decision: every session opens in dump or interview; probe and converge are mid-session moves.
+- Why: a first-time user cannot be asked to pick a posture they have no vocabulary for.
+  Declined: free initial posture — observed cold-starts stall in probe; re-evaluate if
+  session-replay evals show experienced users fighting the default.
+- How to apply: the facilitator's start calibration offers only the two entry moves.
+- Resolves: F2
+```
+
+- IDs `D1, D2, …` unique, append-only [BS-LEDGER-01]. `Decision`, `Why`, `How to apply` are
+  mandatory; `Resolves:` when the commitment closes forks. Amendments and reversals are
+  annotations plus a new entry ("Reversed by D9" on the old; D9 names what it reverses) — never a
+  rewrite. Declined options live inside `Why` per [doctrine.md](doctrine.md).
+
+## ops/capture.md
+
+The facilitator's per-turn append — its one write duty. Lowest possible bar: raw, unpolished,
+everything session-relevant from *both* sides (user substance and facilitator substance —
+diagnoses, informed rejections, definitions, reasoning chains), including residue judged not
+worth pillar filing. Format:
+
+```markdown
+---
+### T14 · 2026-07-08T14:22Z
+
+<raw notes for this turn>
+```
+
+Turn IDs `T#` ascending with an ISO timestamp — the timestamp is what compose-freshness checks
+against [BS-COMPOSE-02]. Never distill here; distillation is the twin's job.
+
+## ops/sync-log.md
+
+Paired-written, one pair per twin dispatch:
+
+```
+S4 | gate: on-demand | dispatched: 2026-07-08T14:25Z | scope: full reconcile + compose
+S4 → reconciled | 2026-07-08T14:29Z | 4 edits · 2 new forks · 6 open · untouched: risks
+```
+
+The **facilitator** writes the dispatch line as it dispatches; the **twin** appends the result
+line (`reconciled` or `failed`) on return — no single author holds both sides. Every dispatch
+line must acquire a result line; only the newest entry may be unpaired (in flight) [BS-SYNC-01].
+A `failed` result is surfaced to the user at the next turn break and re-run at the next gate.
+
+## ops/manifest.md
+
+Created by the stop pipeline; gates the harvest apply:
+
+```markdown
+# Harvest manifest — {topic}
+
+Round: 1
+Status: proposed | approved | applied
+
+| # | What | Source | Destination | Action |
+|---|------|--------|-------------|--------|
+| 1 | consolidated source of truth | thesis + fragments + ledger | docs/features/{x}.md | create |
+| 2 | parked fork F7 | forks.md | docs/architecture/open-questions.md | append |
+
+## Uselessness test
+
+- Result: pass | fail
+- Cold-reader allowed paths: <the destination docs above>
+- Gaps: none | <named gaps → next Round>
+```
+
+Every parked fork and every fragment must have a row [BS-MANIFEST-01]. `Status: approved` is set
+only after the user approves; gap fixes re-enter as a new `Round` with the same approval
+requirement. After apply, no destination doc may link into the session folder [BS-HARVEST-01];
+the move to history requires a recorded passing uselessness test [BS-USELESS-01].
+
+## Detector
+
+`node scripts/detector.mjs <session-folder> [--gate=session|manifest|move] [--json]`
+
+- `session` (default) — the always-on integrity rules; run at any gate.
+- `manifest` — adds the convergence gates (zero open forks, full aspect coverage, fresh compose);
+  the twin may not construct a manifest while any of these fail.
+- `move` — adds the post-apply gates (manifest applied, uselessness pass recorded, no links into
+  scaffolding); the folder may not move while any fail.
+
+Exit code 0 = clean, 1 = violations (listed with rule IDs), 2 = unusable input. Rules degrade
+gracefully: no git context ⇒ BS-OPS-02 reports `skipped`, never blocks. Rule IDs are stable —
+consumers (the twin, the evals, the maintenance census) key on them.

package/data/harnesses/apollo/skills/brainstorm/scripts/detector.mjs

@@ -0,0 +1,460 @@
+#!/usr/bin/env node
+// skills/brainstorm/scripts/detector.mjs - mechanical integrity checks for a brainstorm session folder.
+// Contract: references/session-schema.md. Rule IDs are stable; consumers key on them.
+// Usage: node detector.mjs <session-folder> [--gate=session|manifest|move] [--json]
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, basename, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+const GATES = ['session', 'manifest', 'move'];
+
+// ---------- shared parsing ----------
+
+function readIf(path) {
+    return existsSync(path) ? readFileSync(path, 'utf8') : null;
+}
+
+function parseState(text) {
+    if (text == null) return null;
+    const field = (name) => {
+        const m = text.match(new RegExp(`^- ${name}:\\s*(.+)$`, 'm'));
+        return m ? m[1].trim() : null;
+    };
+    const aspects = [];
+    const mapSection = text.split(/^## Aspect map\s*$/m)[1];
+    if (mapSection != null) {
+        for (const line of mapSection.split('\n')) {
+            const m = line.match(/^- (.+?) — (.+?) → (.+)$/);
+            if (m) {
+                aspects.push({
+                    name: m[1].trim(),
+                    refs: m[3].split(',').map((r) => r.trim()).filter(Boolean),
+                });
+            }
+        }
+    }
+    return {
+        status: field('Status'),
+        posture: field('Posture'),
+        started: field('Started'),
+        sitting: field('Sitting'),
+        lastCompose: field('Last compose'),
+        hasAspectSection: mapSection != null,
+        aspects,
+    };
+}
+
+// Fork entries: "## F3 — title [open]" / "[parked → destination]"
+function parseForks(text) {
+    if (text == null) return [];
+    const forks = [];
+    const re = /^## (F\d+) — (.*?)\s*\[(open|parked → .+?)\]\s*$/gm;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        const start = m.index + m[0].length;
+        const next = text.indexOf('\n## ', start);
+        const body = text.slice(start, next === -1 ? undefined : next);
+        forks.push({
+            id: m[1],
+            title: m[2],
+            state: m[3] === 'open' ? 'open' : 'parked',
+            destination: m[3].startsWith('parked') ? m[3].replace('parked →', '').trim() : null,
+            closesWhen: /^- Closes when:[ \t]*\S/m.test(body),
+            raisedBy: (body.match(/^- Raised by:\s*(.+)$/m) || [])[1] || null,
+        });
+    }
+    return forks;
+}
+
+// Ledger entries: "## D4 — title"
+function parseLedger(text) {
+    if (text == null) return [];
+    const entries = [];
+    const re = /^## (D\d+) — (.+)$/gm;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        const start = m.index + m[0].length;
+        const next = text.indexOf('\n## ', start);
+        const body = text.slice(start, next === -1 ? undefined : next);
+        entries.push({
+            id: m[1],
+            title: m[2],
+            hasDecision: /^- Decision:[ \t]*\S/m.test(body),
+            hasWhy: /^- Why:[ \t]*\S/m.test(body),
+            hasHow: /^- How to apply:[ \t]*\S/m.test(body),
+            resolves: [...body.matchAll(/^- Resolves:\s*(.+)$/gm)]
+                .flatMap((r) => r[1].match(/F\d+/g) || []),
+        });
+    }
+    return entries;
+}
+
+// Sync log: dispatch "S4 | gate: x | dispatched: ts | scope: y"
+//           result   "S4 → reconciled|failed | ts | report"
+function parseSyncLog(text) {
+    if (text == null) return { dispatches: [], results: [] };
+    const dispatches = [];
+    const results = [];
+    for (const line of text.split('\n')) {
+        let m = line.match(/^(S\d+) \| gate: (\S+) \| dispatched: (\S+)/);
+        if (m) { dispatches.push({ id: m[1], gate: m[2], at: m[3], line }); continue; }
+        m = line.match(/^(S\d+) → (reconciled|failed)\b/);
+        if (m) results.push({ id: m[1], outcome: m[2] });
+    }
+    return { dispatches, results };
+}
+
+// Capture: "### T14 · 2026-07-08T14:22Z"
+function parseCapture(text) {
+    if (text == null) return [];
+    return [...text.matchAll(/^### (T\d+) · (\S+)\s*$/gm)].map((m) => ({ id: m[1], at: m[2] }));
+}
+
+function parseManifest(text) {
+    if (text == null) return null;
+    const rows = [...text.matchAll(/^\|\s*\d+\s*\|(.+?)\|(.+?)\|(.+?)\|(.+?)\|\s*$/gm)].map((m) => ({
+        what: m[1].trim(), source: m[2].trim(), destination: m[3].trim(), action: m[4].trim(),
+    }));
+    const status = (text.match(/^Status:\s*(\S+)/m) || [])[1] || null;
+    const uSection = text.split(/^## Uselessness test\s*$/m)[1] || null;
+    return {
+        status,
+        rows,
+        uselessness: uSection == null ? null : {
+            result: (uSection.match(/^- Result:\s*(\S+)/m) || [])[1] || null,
+            gaps: (uSection.match(/^- Gaps:\s*(.+)$/m) || [])[1] || null,
+        },
+    };
+}
+
+// ---------- rule registry ----------
+// Each rule: { id, gate, check(ctx) -> [] | [messages] | 'skipped' }
+
+const RULES = [
+    {
+        id: 'BS-STATE-01',
+        gate: 'session',
+        title: 'state.md present and valid',
+        check: ({ state }) => {
+            if (state == null) return ['state.md missing'];
+            const out = [];
+            if (!['open', 'stopping', 'harvested'].includes(state.status)) out.push(`Status invalid: ${state.status}`);
+            if (!state.started) out.push('Started missing');
+            if (!['single', 'multi'].includes(state.sitting)) out.push(`Sitting invalid: ${state.sitting}`);
+            if (!state.lastCompose) out.push('Last compose missing');
+            if (!state.posture) out.push('Posture missing');
+            return out;
+        },
+    },
+    {
+        id: 'BS-STATE-02',
+        gate: 'session',
+        title: 'aspect map present with at least one aspect',
+        check: ({ state }) => {
+            if (state == null) return ['state.md missing'];
+            if (!state.hasAspectSection) return ['no "## Aspect map" section'];
+            if (state.aspects.length === 0) return ['aspect map has no parseable aspects'];
+            return [];
+        },
+    },
+    {
+        id: 'BS-ASPECT-01',
+        gate: 'session',
+        title: 'aspect refs resolve',
+        check: ({ state, forks, ledger, folder }) => {
+            if (state == null) return [];
+            const forkIds = new Set(forks.map((f) => f.id));
+            const ledgerIds = new Set(ledger.map((d) => d.id));
+            const resolvedForkIds = new Set(ledger.flatMap((d) => d.resolves));
+            const out = [];
+            for (const a of state.aspects) {
+                for (const ref of a.refs) {
+                    if (ref === 'none yet' || ref === 'thesis') continue;
+                    if (/^F\d+$/.test(ref)) {
+                        // a fork ref may point at an open fork or one already resolved into the ledger
+                        if (!forkIds.has(ref) && !resolvedForkIds.has(ref)) out.push(`aspect "${a.name}" → ${ref}: no such fork (open or resolved)`);
+                    } else if (/^D\d+$/.test(ref)) {
+                        if (!ledgerIds.has(ref)) out.push(`aspect "${a.name}" → ${ref}: no such ledger entry`);
+                    } else if (ref.startsWith('fragment:')) {
+                        const name = ref.slice('fragment:'.length);
+                        if (!existsSync(join(folder, 'fragments', `${name}.md`))) out.push(`aspect "${a.name}" → ${ref}: fragments/${name}.md missing`);
+                    } else {
+                        out.push(`aspect "${a.name}" → unrecognized ref "${ref}"`);
+                    }
+                }
+            }
+            return out;
+        },
+    },
+    {
+        id: 'BS-ASPECT-02',
+        gate: 'manifest',
+        title: 'no uncovered aspects at the manifest gate',
+        check: ({ state }) => {
+            if (state == null) return [];
+            return state.aspects
+                .filter((a) => a.refs.length === 0 || a.refs.includes('none yet'))
+                .map((a) => `aspect "${a.name}" has no content`);
+        },
+    },
+    {
+        id: 'BS-THESIS-01',
+        gate: 'session',
+        title: 'thesis has the mandated shape and stamp',
+        check: ({ thesis }) => {
+            if (thesis == null) return ['thesis.md missing'];
+            const out = [];
+            if (!/^Current as of:\s*\S/m.test(thesis)) out.push('Current as of: stamp missing');
+            for (const s of ['## Claim', '## Argument', '## What changed']) {
+                if (!thesis.includes(s)) out.push(`section "${s}" missing`);
+            }
+            return out;
+        },
+    },
+    {
+        id: 'BS-COMPOSE-01',
+        gate: 'session',
+        title: 'thesis stamp matches state.md Last compose',
+        check: ({ state, thesis }) => {
+            if (state == null || thesis == null || state.lastCompose === 'never') return [];
+            const stamp = (thesis.match(/^Current as of:\s*(\S+)/m) || [])[1];
+            return stamp === state.lastCompose ? []
+                : [`thesis stamp ${stamp} ≠ state Last compose ${state.lastCompose}`];
+        },
+    },
+    {
+        id: 'BS-COMPOSE-02',
+        gate: 'manifest',
+        title: 'compose fresher than the newest capture entry',
+        check: ({ state, capture }) => {
+            if (state == null || capture.length === 0) return [];
+            if (state.lastCompose === 'never') return ['no compose has ever run'];
+            const newest = capture[capture.length - 1].at;
+            return state.lastCompose >= newest ? []
+                : [`last compose ${state.lastCompose} predates newest capture ${newest}`];
+        },
+    },
+    {
+        id: 'BS-FORK-01',
+        gate: 'session',
+        title: 'forks well-formed (unique IDs, close conditions, valid state)',
+        check: ({ forks }) => {
+            const out = [];
+            const seen = new Set();
+            for (const f of forks) {
+                if (seen.has(f.id)) out.push(`duplicate fork id ${f.id}`);
+                seen.add(f.id);
+                if (!f.closesWhen) out.push(`${f.id} has no "Closes when:"`);
+                if (f.state === 'parked' && !f.destination) out.push(`${f.id} parked without destination`);
+            }
+            return out;
+        },
+    },
+    {
+        id: 'BS-FORK-02',
+        gate: 'session',
+        title: 'no fork both resolved in the ledger and still open',
+        check: ({ forks, ledger }) => {
+            const open = new Set(forks.filter((f) => f.state === 'open').map((f) => f.id));
+            const out = [];
+            for (const d of ledger) {
+                for (const f of d.resolves) {
+                    if (open.has(f)) out.push(`${d.id} resolves ${f} but ${f} is still open in forks.md`);
+                }
+            }
+            return out;
+        },
+    },
+    {
+        id: 'BS-FORK-03',
+        gate: 'manifest',
+        title: 'zero open forks at the manifest gate',
+        check: ({ forks }) => forks.filter((f) => f.state === 'open').map((f) => `${f.id} is open`),
+    },
+    {
+        id: 'BS-LEDGER-01',
+        gate: 'session',
+        title: 'ledger entries carry the mandatory fields, IDs unique',
+        check: ({ ledger }) => {
+            const out = [];
+            const seen = new Set();
+            for (const d of ledger) {
+                if (seen.has(d.id)) out.push(`duplicate ledger id ${d.id}`);
+                seen.add(d.id);
+                if (!d.hasDecision) out.push(`${d.id} missing Decision`);
+                if (!d.hasWhy) out.push(`${d.id} missing Why`);
+                if (!d.hasHow) out.push(`${d.id} missing How to apply`);
+            }
+            return out;
+        },
+    },
+    {
+        id: 'BS-OPS-01',
+        gate: 'session',
+        title: 'ops/ hygiene: .gitignore present and covering',
+        check: ({ folder }) => {
+            const gi = readIf(join(folder, 'ops', '.gitignore'));
+            if (gi == null) return ['ops/.gitignore missing'];
+            return gi.split('\n').some((l) => l.trim() === '*') ? [] : ['ops/.gitignore does not contain "*"'];
+        },
+    },
+    {
+        id: 'BS-OPS-02',
+        gate: 'session',
+        title: 'ops/ never committed',
+        check: ({ folder }) => {
+            try {
+                const tracked = execFileSync('git', ['ls-files', '--', 'ops'], {
+                    cwd: folder, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+                }).trim();
+                return tracked === '' ? [] : [`ops/ files tracked by git: ${tracked.split('\n').join(', ')}`];
+            } catch {
+                return 'skipped'; // no git context — degrade, never block
+            }
+        },
+    },
+    {
+        id: 'BS-SYNC-01',
+        gate: 'session',
+        title: 'sync-log pairing: every dispatch has a result (newest may be in flight)',
+        check: ({ sync }) => {
+            const resulted = new Set(sync.results.map((r) => r.id));
+            const unpaired = sync.dispatches.filter((d) => !resulted.has(d.id));
+            if (unpaired.length === 0) return [];
+            const last = sync.dispatches[sync.dispatches.length - 1];
+            if (unpaired.length === 1 && unpaired[0].id === last.id) return []; // in flight
+            return unpaired.map((d) => `${d.id} dispatched but never resulted`);
+        },
+    },
+    {
+        id: 'BS-SYNC-02',
+        gate: 'session',
+        title: 'twin attributions cite a reconciled sync entry',
+        check: ({ forks, sync }) => {
+            const reconciled = new Set(sync.results.filter((r) => r.outcome === 'reconciled').map((r) => r.id));
+            const out = [];
+            for (const f of forks) {
+                if (f.raisedBy == null) continue;
+                const m = f.raisedBy.match(/^twin\s*\((S\d+)\)/);
+                if (f.raisedBy.startsWith('twin') && !m) { out.push(`${f.id} raised by twin without a sync id`); continue; }
+                if (m && !reconciled.has(m[1])) out.push(`${f.id} cites ${m[1]} which never reconciled`);
+            }
+            return out;
+        },
+    },
+    {
+        id: 'BS-MANIFEST-01',
+        gate: 'manifest',
+        title: 'manifest routes every parked fork and every fragment',
+        check: ({ forks, manifest, folder }) => {
+            if (manifest == null) return ['ops/manifest.md missing'];
+            const out = [];
+            const text = manifest.rows.map((r) => `${r.what} ${r.source}`).join('\n');
+            for (const f of forks.filter((x) => x.state === 'parked')) {
+                if (!text.includes(f.id)) out.push(`parked ${f.id} has no manifest row`);
+            }
+            const fragDir = join(folder, 'fragments');
+            if (existsSync(fragDir)) {
+                for (const frag of readdirSync(fragDir).filter((n) => n.endsWith('.md'))) {
+                    if (!text.includes(frag) && !text.includes(basename(frag, '.md'))) {
+                        out.push(`fragments/${frag} has no manifest row`);
+                    }
+                }
+            }
+            return out;
+        },
+    },
+    {
+        id: 'BS-HARVEST-01',
+        gate: 'move',
+        title: 'no harvested destination links into the session folder',
+        check: ({ manifest, folder }) => {
+            if (manifest == null) return ['ops/manifest.md missing'];
+            const slug = basename(resolve(folder));
+            const out = [];
+            for (const row of manifest.rows) {
+                const dest = row.destination;
+                if (!dest || !dest.endsWith('.md')) continue;
+                const destPath = resolve(folder, '..', '..', '..', dest); // repo root = 3 up from docs/research/{slug}
+                const text = readIf(destPath) ?? readIf(resolve(dest));
+                if (text == null) { out.push(`destination ${dest} not found on disk`); continue; }
+                if (text.includes(slug)) out.push(`${dest} links into the session folder (${slug})`);
+            }
+            return out;
+        },
+    },
+    {
+        id: 'BS-USELESS-01',
+        gate: 'move',
+        title: 'recorded passing uselessness test with no gaps',
+        check: ({ manifest }) => {
+            if (manifest?.uselessness == null) return ['manifest has no "## Uselessness test" section'];
+            const out = [];
+            if (manifest.uselessness.result !== 'pass') out.push(`result is "${manifest.uselessness.result}"`);
+            if (manifest.uselessness.gaps !== 'none') out.push(`gaps recorded: ${manifest.uselessness.gaps}`);
+            if (manifest.status !== 'applied') out.push(`manifest status is "${manifest.status}", not applied`);
+            return out;
+        },
+    },
+];
+
+// ---------- runner ----------
+
+export function runDetector(folder, gate = 'session') {
+    const ctx = {
+        folder,
+        state: parseState(readIf(join(folder, 'state.md'))),
+        thesis: readIf(join(folder, 'thesis.md')),
+        forks: parseForks(readIf(join(folder, 'forks.md'))),
+        ledger: parseLedger(readIf(join(folder, 'ledger.md'))),
+        capture: parseCapture(readIf(join(folder, 'ops', 'capture.md'))),
+        sync: parseSyncLog(readIf(join(folder, 'ops', 'sync-log.md'))),
+        manifest: parseManifest(readIf(join(folder, 'ops', 'manifest.md'))),
+    };
+    const activeGates = GATES.slice(0, GATES.indexOf(gate) + 1); // gates are cumulative
+    const results = [];
+    for (const rule of RULES) {
+        if (!activeGates.includes(rule.gate)) continue;
+        const res = rule.check(ctx);
+        if (res === 'skipped') results.push({ id: rule.id, title: rule.title, status: 'skipped', messages: [] });
+        else results.push({ id: rule.id, title: rule.title, status: res.length === 0 ? 'pass' : 'fail', messages: res });
+    }
+    return results;
+}
+
+function main() {
+    const args = process.argv.slice(2);
+    const folder = args.find((a) => !a.startsWith('--'));
+    const gate = (args.find((a) => a.startsWith('--gate=')) || '--gate=session').split('=')[1];
+    const asJson = args.includes('--json');
+
+    if (!folder || !existsSync(folder) || !statSync(folder).isDirectory()) {
+        console.error('usage: node detector.mjs <session-folder> [--gate=session|manifest|move] [--json]');
+        process.exit(2);
+    }
+    if (!GATES.includes(gate)) {
+        console.error(`unknown gate "${gate}" — one of: ${GATES.join(', ')}`);
+        process.exit(2);
+    }
+
+    const results = runDetector(resolve(folder), gate);
+    const failed = results.filter((r) => r.status === 'fail');
+
+    if (asJson) {
+        console.log(JSON.stringify({ folder: resolve(folder), gate, results }, null, 2));
+    } else {
+        for (const r of results) {
+            const mark = r.status === 'pass' ? '✓' : r.status === 'skipped' ? '~' : '✗';
+            console.log(`${mark} ${r.id} — ${r.title}`);
+            for (const m of r.messages) console.log(`    ${m}`);
+        }
+        console.log(`\n${failed.length === 0 ? 'clean' : `${failed.length} rule(s) failing`} at gate "${gate}"`);
+    }
+    process.exit(failed.length === 0 ? 0 : 1);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    main();
+}