specweave 2.1.0 → 2.2.1

package/dist/src/core/jev/redact.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Jev — the single redaction choke point.
+ *
+ * Every byte that leaves this machine for the System One endpoint goes through
+ * {@link redactSecrets} first: the client scrubs the serialized state before any
+ * request, and the PreToolUse Bash guard scrubs the command text it scores.
+ * One function, one set of patterns, one set of markers — a second copy is how a
+ * key eventually ships.
+ *
+ * Layers, in order:
+ *   1. the shared handoff scrubber (`sk-…`, `sk-or-…`, `ghp_`/`gho_`/`ghs_`,
+ *      `vsk_`, `xox[abp]-`, `AKIA…`/`ASIA…`, `Bearer …`, PEM headers,
+ *      `password=`, `api_key=`);
+ *   2. key shapes it does not carry (`github_pat_…`, JWT-looking `eyJ….….…`);
+ *   3. command-shaped secrets (`scheme:// USER : PASS @host`, `--otp=`/`--token …`,
+ *      `SOMETHING_TOKEN=value`).
+ *
+ * Later layers carry a `(?!\[REDACTED)` guard so an already-masked span is never
+ * masked twice. Markers are normalised to `<REDACTED-…>` at the end: masking
+ * removes text, and removed text could otherwise turn a command the guard's
+ * prefilter calls 'check' into one it calls 'skip' (`echo PASSWORD="x; rm -rf ~"`
+ * → `echo PASSWORD=<…>`). `<` is in the prefilter's shell-power set, so a
+ * redacted command always still reaches Jev.
+ *
+ * HEURISTIC, never a guarantee: zero redactions does not mean the text is clean.
+ * That is why every Jev integration is opt-in and the docs state the export.
+ *
+ * @module core/jev/redact
+ */
+/**
+ * Mask secret-shaped values before text leaves this machine.
+ *
+ * The markers keep the text's shape, so a command still scores the same way for
+ * scope and destructiveness and a state object still reads the same way.
+ *
+ * @param text - anything about to be sent to the System One endpoint
+ * @returns the redacted text and how many spans were masked (0 = nothing matched,
+ *          which is not the same as "clean")
+ */
+export declare function redactSecrets(text: string): {
+    text: string;
+    redactions: number;
+};
+//# sourceMappingURL=redact.d.ts.map

package/dist/src/core/jev/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../../../src/core/jev/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AA4DH;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAiBhF"}

package/dist/src/core/jev/redact.js

@@ -0,0 +1,102 @@
+/**
+ * Jev — the single redaction choke point.
+ *
+ * Every byte that leaves this machine for the System One endpoint goes through
+ * {@link redactSecrets} first: the client scrubs the serialized state before any
+ * request, and the PreToolUse Bash guard scrubs the command text it scores.
+ * One function, one set of patterns, one set of markers — a second copy is how a
+ * key eventually ships.
+ *
+ * Layers, in order:
+ *   1. the shared handoff scrubber (`sk-…`, `sk-or-…`, `ghp_`/`gho_`/`ghs_`,
+ *      `vsk_`, `xox[abp]-`, `AKIA…`/`ASIA…`, `Bearer …`, PEM headers,
+ *      `password=`, `api_key=`);
+ *   2. key shapes it does not carry (`github_pat_…`, JWT-looking `eyJ….….…`);
+ *   3. command-shaped secrets (`scheme:// USER : PASS @host`, `--otp=`/`--token …`,
+ *      `SOMETHING_TOKEN=value`).
+ *
+ * Later layers carry a `(?!\[REDACTED)` guard so an already-masked span is never
+ * masked twice. Markers are normalised to `<REDACTED-…>` at the end: masking
+ * removes text, and removed text could otherwise turn a command the guard's
+ * prefilter calls 'check' into one it calls 'skip' (`echo PASSWORD="x; rm -rf ~"`
+ * → `echo PASSWORD=<…>`). `<` is in the prefilter's shell-power set, so a
+ * redacted command always still reaches Jev.
+ *
+ * HEURISTIC, never a guarantee: zero redactions does not mean the text is clean.
+ * That is why every Jev integration is opt-in and the docs state the export.
+ *
+ * @module core/jev/redact
+ */
+import { scrubSecrets, totalRedactions } from '../session/handoff-secret-scrub.js';
+/**
+ * Key shapes the shared scrubber does not carry.
+ *
+ * Fixed-literal prefixes, so they can never match inside a `[REDACTED-…]` marker.
+ */
+const KEY_SHAPE_PATTERNS = [
+    {
+        // GitHub fine-grained PAT: `github_pat_11ABCDEF0…`
+        type: 'github-pat',
+        regex: /github_pat_[A-Za-z0-9_]{20,}/g,
+        replace: '[REDACTED-github-pat]',
+    },
+    {
+        // JWT-looking: `eyJhbGciOi….eyJzdWIi….<signature>` (the signature is optional).
+        type: 'jwt',
+        regex: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}(?:\.[A-Za-z0-9_-]+)?/g,
+        replace: '[REDACTED-jwt]',
+    },
+];
+/**
+ * Command-shaped secrets: the value is identified by the flag or variable in
+ * front of it rather than by its own shape.
+ */
+const COMMAND_SECRET_PATTERNS = [
+    {
+        // `psql postgres:// USER : PASS @host/db`, `git clone https:// U : TOK @github.com/...`
+        type: 'url-credentials',
+        regex: /([a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]*@/gi,
+        replace: '$1[REDACTED-url-credentials]@',
+    },
+    {
+        // `npm publish --otp=123456`, `--token <value>`, `--password=…`
+        type: 'secret-flag',
+        regex: /(?<![\w-])(--?(?:otp|tokens?|passwords?|passwd|secrets?|api[-_]?keys?|access[-_]?tokens?|credentials?)[=\s])(?!\[REDACTED)("[^"]*"|'[^']*'|\S+)/gi,
+        replace: '$1[REDACTED-secret-flag]',
+    },
+    {
+        // `GITHUB_TOKEN=ghp_… cmd`, `MY_API_KEY="…"`, `DB_PASSWORD=…`
+        type: 'env-secret',
+        regex: /(^|[\s;&|(])([A-Za-z_][A-Za-z0-9_]*(?:TOKEN|SECRET|PASSWORD|PASSWD|KEY|CREDENTIALS?)[A-Za-z0-9_]*=)(?!\[REDACTED)("[^"]*"|'[^']*'|\S*)/gi,
+        replace: '$1$2[REDACTED-env-secret]',
+    },
+];
+const EXTRA_PATTERNS = [...KEY_SHAPE_PATTERNS, ...COMMAND_SECRET_PATTERNS];
+/**
+ * Mask secret-shaped values before text leaves this machine.
+ *
+ * The markers keep the text's shape, so a command still scores the same way for
+ * scope and destructiveness and a state object still reads the same way.
+ *
+ * @param text - anything about to be sent to the System One endpoint
+ * @returns the redacted text and how many spans were masked (0 = nothing matched,
+ *          which is not the same as "clean")
+ */
+export function redactSecrets(text) {
+    const base = scrubSecrets(text ?? '');
+    let redacted = base.scrubbed;
+    let redactions = totalRedactions(base.counts);
+    for (const { regex, replace } of EXTRA_PATTERNS) {
+        regex.lastIndex = 0;
+        const hits = redacted.match(regex);
+        if (!hits)
+            continue;
+        redactions += hits.length;
+        regex.lastIndex = 0;
+        redacted = redacted.replace(regex, replace);
+    }
+    if (redactions > 0)
+        redacted = redacted.replace(/\[REDACTED-([A-Za-z-]+)\]/g, '<REDACTED-$1>');
+    return { text: redacted, redactions };
+}
+//# sourceMappingURL=redact.js.map

package/dist/src/core/jev/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../../../src/core/jev/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AASnF;;;;GAIG;AACH,MAAM,kBAAkB,GAAiC;IACvD;QACE,mDAAmD;QACnD,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,+BAA+B;QACtC,OAAO,EAAE,uBAAuB;KACjC;IACD;QACE,gFAAgF;QAChF,IAAI,EAAE,KAAK;QACX,KAAK,EAAE,mEAAmE;QAC1E,OAAO,EAAE,gBAAgB;KAC1B;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,uBAAuB,GAAiC;IAC5D;QACE,wFAAwF;QACxF,IAAI,EAAE,iBAAiB;QACvB,KAAK,EAAE,+CAA+C;QACtD,OAAO,EAAE,+BAA+B;KACzC;IACD;QACE,gEAAgE;QAChE,IAAI,EAAE,aAAa;QACnB,KAAK,EACH,mJAAmJ;QACrJ,OAAO,EAAE,0BAA0B;KACpC;IACD;QACE,8DAA8D;QAC9D,IAAI,EAAE,YAAY;QAClB,KAAK,EACH,0IAA0I;QAC5I,OAAO,EAAE,2BAA2B;KACrC;CACF,CAAC;AAEF,MAAM,cAAc,GAAiC,CAAC,GAAG,kBAAkB,EAAE,GAAG,uBAAuB,CAAC,CAAC;AAEzG;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IACtC,IAAI,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC7B,IAAI,UAAU,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAE9C,KAAK,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,cAAc,EAAE,CAAC;QAChD,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC;QACpB,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,UAAU,IAAI,IAAI,CAAC,MAAM,CAAC;QAC1B,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC;QACpB,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED,IAAI,UAAU,GAAG,CAAC;QAAE,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,4BAA4B,EAAE,eAAe,CAAC,CAAC;IAE/F,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AACxC,CAAC"}

package/dist/src/core/jev/usage.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Jev usage ledger — append-only JSONL at `.specweave/state/jev-usage.jsonl`
+ *
+ * Every Jev call writes one line (tokens, cost, latency, ok). Reading is tolerant:
+ * a truncated or corrupt line is skipped, never thrown. Nothing here stores a key.
+ *
+ * @module core/jev/usage
+ */
+export interface JevUsageRecord {
+    at: string;
+    kind: string;
+    provider: string;
+    model: string;
+    input_tokens: number;
+    output_tokens: number;
+    cost?: number;
+    latencyMs: number;
+    /** Secret-shaped spans masked out of the request state before it was sent. */
+    redactions?: number;
+    ok: boolean;
+}
+export interface JevUsageSummary {
+    calls: number;
+    input_tokens: number;
+    cost: number;
+    byKind: Record<string, number>;
+    since?: string;
+}
+/** Absolute path of the ledger for a project root. */
+export declare function usageLogPath(projectRoot: string): string;
+/**
+ * Append one record. Best-effort: never throws (the caller is mid-decision).
+ * O_APPEND keeps concurrent agents from interleaving partial lines.
+ */
+export declare function appendUsage(projectRoot: string, rec: JevUsageRecord): void;
+/** Totals over the whole ledger. Missing file → zeroes. Bad lines → skipped. */
+export declare function readUsageSummary(projectRoot: string): JevUsageSummary;
+//# sourceMappingURL=usage.d.ts.map

package/dist/src/core/jev/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../../../src/core/jev/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,OAAO,CAAC;CACb;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,sDAAsD;AACtD,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI,CAQ1E;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAuCrE"}

package/dist/src/core/jev/usage.js

@@ -0,0 +1,70 @@
+/**
+ * Jev usage ledger — append-only JSONL at `.specweave/state/jev-usage.jsonl`
+ *
+ * Every Jev call writes one line (tokens, cost, latency, ok). Reading is tolerant:
+ * a truncated or corrupt line is skipped, never thrown. Nothing here stores a key.
+ *
+ * @module core/jev/usage
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/** Absolute path of the ledger for a project root. */
+export function usageLogPath(projectRoot) {
+    return path.join(projectRoot, '.specweave', 'state', 'jev-usage.jsonl');
+}
+/**
+ * Append one record. Best-effort: never throws (the caller is mid-decision).
+ * O_APPEND keeps concurrent agents from interleaving partial lines.
+ */
+export function appendUsage(projectRoot, rec) {
+    try {
+        const filePath = usageLogPath(projectRoot);
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.appendFileSync(filePath, JSON.stringify(rec) + '\n', { flag: 'a' });
+    }
+    catch {
+        // Ledger writes are advisory; a full disk must not break a Jev decision.
+    }
+}
+/** Totals over the whole ledger. Missing file → zeroes. Bad lines → skipped. */
+export function readUsageSummary(projectRoot) {
+    const summary = { calls: 0, input_tokens: 0, cost: 0, byKind: {} };
+    let raw;
+    try {
+        const filePath = usageLogPath(projectRoot);
+        if (!fs.existsSync(filePath))
+            return summary;
+        raw = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return summary;
+    }
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (!rec || typeof rec !== 'object')
+            continue;
+        summary.calls += 1;
+        if (typeof rec.input_tokens === 'number' && Number.isFinite(rec.input_tokens)) {
+            summary.input_tokens += rec.input_tokens;
+        }
+        if (typeof rec.cost === 'number' && Number.isFinite(rec.cost)) {
+            summary.cost += rec.cost;
+        }
+        const kind = typeof rec.kind === 'string' && rec.kind ? rec.kind : 'unknown';
+        summary.byKind[kind] = (summary.byKind[kind] ?? 0) + 1;
+        if (typeof rec.at === 'string' && rec.at && (!summary.since || rec.at < summary.since)) {
+            summary.since = rec.at;
+        }
+    }
+    return summary;
+}
+//# sourceMappingURL=usage.js.map

package/dist/src/core/jev/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../../../src/core/jev/usage.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/model-selection.d.ts

@@ -8,6 +8,8 @@
  * - Haiku: Simple/cheap operations, translations, mechanical work
  * - Opus: Default for all complex work, architecture, creative problem-solving
  */
+import type { JevClient } from '../core/jev/client.js';
+import type { classifyTask } from '../core/jev/decide.js';
 export type ModelTier = 'haiku' | 'sonnet' | 'opus';
 export interface Task {
     id: string;
@@ -71,4 +73,51 @@ export declare function calculateCostSavings(tasksWithModels: Map<string, ModelT
     savings: number;
     savingsPercent: number;
 };
+/**
+ * Where a tier recommendation came from.
+ * - `jev`       — TypeSafe System One classified the task
+ * - `heuristic` — the keyword scorer in {@link detectModelForTask}
+ */
+export type ModelTierSource = 'jev' | 'heuristic';
+/** {@link DetectionResult} plus the decision's provenance. */
+export interface TierSelection extends DetectionResult {
+    source: ModelTierSource;
+    /** Latency of the Jev call, when one happened. */
+    latencyMs?: number;
+    /** Cost of the Jev call in USD, when reported. */
+    cost?: number;
+}
+/**
+ * Injection points for tests and callers that already hold a client/config.
+ * Nothing here is required: the defaults read the project config.
+ */
+export interface SelectModelTierDeps {
+    /** Project root used to load `.specweave/config.json`. */
+    projectRoot?: string;
+    /** Force the Jev path on/off (skips config loading when provided). */
+    enabled?: boolean;
+    /** Force modelRouting on/off (skips config loading when provided). */
+    modelRouting?: boolean;
+    /** Confidence floor below which the tier falls back to opus. */
+    routeThreshold?: number;
+    /** A ready client. `null` means "no client available" (heuristic path). */
+    client?: JevClient | null;
+    /** Override the classifier (tests). */
+    classify?: typeof classifyTask;
+}
+/**
+ * Pick a model tier for a task, preferring Jev when the project opted in.
+ *
+ * Behaviour (AC-07):
+ * - Jev off, no key, error, timeout → the keyword heuristic, `source: 'heuristic'`
+ * - Jev on → `{ model: tier, reasoning: 'jev:<complexity>', source: 'jev' }`
+ * - Jev on but confidence < `thresholds.route` → opus, `reasoning: 'jev:low-confidence'`
+ *
+ * Never throws: every failure path degrades to the heuristic.
+ */
+export declare function selectModelTierForTask(task: Task, options?: {
+    specDetailLevel?: number;
+    hasDetailedPlan?: boolean;
+    isArchitectural?: boolean;
+}, deps?: SelectModelTierDeps): Promise<TierSelection>;
 //# sourceMappingURL=model-selection.d.ts.map

package/dist/src/utils/model-selection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-selection.d.ts","sourceRoot":"","sources":["../../../src/utils/model-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEpD,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AA4BD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,EACV,OAAO,GAAE;IACP,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;CACtB,GACL,eAAe,CA6GjB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,IAAI,EAAE,EACb,OAAO,GAAE;IACP,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;CACtB,GACL,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAS9B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAQxD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAU7D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,EAChB,eAAe,GAAE,MAAa,GAC7B,MAAM,CASR;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EACvC,oBAAoB,GAAE,MAAa,GAClC;IACD,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;CACxB,CAkBA"}
+{"version":3,"file":"model-selection.d.ts","sourceRoot":"","sources":["../../../src/utils/model-selection.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/model-selection.js

@@ -205,4 +205,74 @@ export function calculateCostSavings(tasksWithModels, averageTokensPerTask = 200
         savingsPercent
     };
 }
+/**
+ * Pick a model tier for a task, preferring Jev when the project opted in.
+ *
+ * Behaviour (AC-07):
+ * - Jev off, no key, error, timeout → the keyword heuristic, `source: 'heuristic'`
+ * - Jev on → `{ model: tier, reasoning: 'jev:<complexity>', source: 'jev' }`
+ * - Jev on but confidence < `thresholds.route` → opus, `reasoning: 'jev:low-confidence'`
+ *
+ * Never throws: every failure path degrades to the heuristic.
+ */
+export async function selectModelTierForTask(task, options = {}, deps = {}) {
+    const heuristic = () => ({
+        ...detectModelForTask(task, options),
+        source: 'heuristic',
+    });
+    try {
+        const [cfgMod, clientMod, decideMod] = await Promise.all([
+            import('../core/jev/config.js'),
+            import('../core/jev/client.js'),
+            import('../core/jev/decide.js'),
+        ]);
+        let enabled = deps.enabled;
+        let modelRouting = deps.modelRouting;
+        let routeThreshold = deps.routeThreshold;
+        if (enabled === undefined || modelRouting === undefined || routeThreshold === undefined) {
+            const cfg = cfgMod.loadJevConfig(deps.projectRoot);
+            if (enabled === undefined)
+                enabled = cfg.enabled;
+            if (modelRouting === undefined)
+                modelRouting = cfg.modelRouting;
+            if (routeThreshold === undefined)
+                routeThreshold = cfg.thresholds.route;
+        }
+        if (!enabled || !modelRouting)
+            return heuristic();
+        const client = deps.client !== undefined ? deps.client : clientMod.createJevClient(deps.projectRoot);
+        if (!client)
+            return heuristic();
+        const classify = deps.classify ?? decideMod.classifyTask;
+        const decision = await classify(client, {
+            id: task.id,
+            title: task.content,
+            body: task.description ?? '',
+            acs: task.acceptanceCriteria ?? [],
+        });
+        if (!decision.available)
+            return heuristic();
+        if (decision.confidence < routeThreshold) {
+            return {
+                model: 'opus',
+                confidence: decision.confidence,
+                reasoning: 'jev:low-confidence',
+                source: 'jev',
+                latencyMs: decision.latencyMs,
+                cost: decision.cost,
+            };
+        }
+        return {
+            model: decision.tier,
+            confidence: decision.confidence,
+            reasoning: `jev:${decision.complexity}`,
+            source: 'jev',
+            latencyMs: decision.latencyMs,
+            cost: decision.cost,
+        };
+    }
+    catch {
+        return heuristic();
+    }
+}
 //# sourceMappingURL=model-selection.js.map

package/dist/src/utils/model-selection.js.map

@@ -1 +1 @@
-{"version":3,"file":"model-selection.js","sourceRoot":"","sources":["../../../src/utils/model-selection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"model-selection.js","sourceRoot":"","sources":["../../../src/utils/model-selection.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Keep intent, specifications, and verified progress portable across AI coding tools. A local live work board, append-only task evidence, explicit handoffs, and optional GitHub/Jira/Azure DevOps integrations.",
   "type": "module",
   "bin": {

package/plugins/PLUGINS-INDEX.md

@@ -1,13 +1,13 @@
 # SpecWeave plugins index
 
-**Plugins**: 1 (`sw`) · **Skills**: 10 · **Commands**: 0 · **Hooks**: 4
+**Plugins**: 1 (`sw`) · **Skills**: 11 · **Commands**: 0 · **Hooks**: 2 default
 
 The 1.x `commands/` namespace is gone: anything deterministic is a `specweave`
-CLI subcommand, and the model-judgement procedures are the 10 skills below.
+CLI subcommand, and the model-judgement procedures are the 11 skills below.
 
 | Plugin | Triggers | Description |
 |---|---|---|
-| **specweave** (`sw`) | increment, spec, tasks, plan, implement, close, review, team, handoff, sync, GitHub, Jira, ADO, auto, brainstorm, qa | Increment lifecycle: plan → work the ledger → verify → review → complete, with cross-tool handoff and tracker sync |
+| **specweave** (`sw`) | increment, spec, tasks, plan, implement, close, review, team, handoff, sync, GitHub, Jira, ADO, auto, brainstorm, qa, jev, system one | Increment lifecycle: plan → work the ledger → verify → review → complete, with cross-tool handoff, tracker sync and closed-set decisions delegated to Jev |
 
 ## Quick lookup
 
@@ -23,6 +23,16 @@ CLI subcommand, and the model-judgement procedures are the 10 skills below.
 | "Run until done" | `sw:auto` |
 | "What are our options" | `sw:brainstorm` |
 | "Quality check" / "risk assessment" | `sw:qa` |
+| "Jev" / "system one" / a decision whose answers can all be enumerated first | `sw:jev` |
+
+## Hooks
+
+Two by default, registered in `specweave/hooks/hooks.json` as exec-form
+`node hooks/run.mjs <event>`: `SessionStart` and `Stop`. Each one fails open.
+`PreToolUse` is not a default hook — the Jev Bash guard is turned on per project by
+`specweave jev setup --guard-bash`, which writes `jev.guards.bash`, the marker
+`.specweave/state/jev-guard.enabled`, and a `PreToolUse` entry (matcher `Bash`) in that
+project's `.claude/settings.json`. `--no-guard-bash` removes all three.
 
 ## Not in the plugin
 
@@ -30,4 +40,4 @@ CLI subcommand, and the model-judgement procedures are the 10 skills below.
 and install per-project with vskill. See `skills-optional/README.md`.
 
 Deterministic operations are CLI: `specweave status | task | verify | complete | qa |
-handoff | sync | docs | doctor | gc`.
+handoff | sync | docs | doctor | gc | jev`.

package/plugins/specweave/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sw",
-  "description": "Portable intent and verified progress across coding tools. Ten focused workflow skills, two default lifecycle hooks, and a deterministic CLI and live local dashboard.",
-  "version": "2.1.0",
+  "description": "Portable intent and verified progress across coding tools. Eleven focused workflow skills, two default lifecycle hooks, and a deterministic CLI and live local dashboard.",
+  "version": "2.2.1",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"
@@ -20,6 +20,8 @@
     "handoff",
     "github",
     "jira",
-    "azure-devops"
+    "azure-devops",
+    "jev",
+    "system-one"
   ]
 }

package/plugins/specweave/PLUGIN.md

@@ -1,6 +1,6 @@
 # SpecWeave plugin (`sw`)
 
-The Claude Code surface for SpecWeave: **10 skills, 4 hooks, 1 closer agent**.
+The Claude Code surface for SpecWeave: **11 skills, 2 default hooks, 1 closer agent**.
 Everything deterministic lives in the `specweave` CLI; a skill exists only where a
 procedure needs model judgement. There is no `commands/` namespace in 2.0.
 
@@ -18,6 +18,7 @@ procedure needs model judgement. There is no `commands/` namespace in 2.0.
 | `sw:auto` | Unattended loop driven by the Stop hook |
 | `sw:brainstorm` | Expand the option space before committing to one |
 | `sw:qa` | Risk-scored quality assessment (`specweave qa`) |
+| `sw:jev` | Delegate closed-set decisions to Jev (TypeSafe System One): routing, command safety, screening |
 
 Optional procedures (tdd-cycle, e2e, debug, diagrams, release-expert) are **not** in the
 plugin — they ship from `skills-optional/` via
@@ -25,14 +26,25 @@ plugin — they ship from `skills-optional/` via
 
 ## Hooks
 
-Four, all exec-form `node hooks/run.mjs <event>` (no shell, Windows-safe):
+Two by default, both exec-form `node hooks/run.mjs <event>` (no shell, Windows-safe):
 
 | Hook | Job |
 |---|---|
 | `SessionStart` | Inject the active increment + next task as context |
-| `PreToolUse` (Write\|Edit) | Guard writes under `.specweave/increments/` |
 | `Stop` | Drive the `sw:auto` loop; `{}` for every ordinary session |
-| `PreCompact` | Write a handoff doc before context is compacted |
+
+`PreToolUse` is **not** registered by default — `hooks.json` ships `SessionStart` and
+`Stop` only, exactly as in 2.1.0. `PreToolUse` and `PreCompact` stay callable
+compatibility handlers.
+
+The Jev Bash guard is opted into **one project at a time**:
+`specweave jev setup --guard-bash` sets `jev.guards.bash` in `.specweave/config.json`,
+writes the marker `.specweave/state/jev-guard.enabled`, and registers a project-level
+hook in that project's `.claude/settings.json` (`hooks.PreToolUse`, matcher `Bash`,
+command `node "<installed specweave>/plugins/specweave/hooks/run.mjs" pre-tool-use`).
+`specweave jev setup --no-guard-bash` removes all three, and `specweave jev doctor` shows
+the marker and the project hook. This is a Claude Code surface only; other tools call
+`specweave jev guard "<command>"` explicitly before running anything unattended.
 
 ## Agents
 

package/plugins/specweave/hooks/run-worker.mjs

@@ -19,7 +19,9 @@
  *   4. `npm root -g` (result cached in a per-user private file under ~/.specweave)
  *
  * Fast path: PreToolUse for a file outside `.specweave/increments/` prints `{}`
- * without loading the CLI at all (the guards only concern increment files).
+ * without loading the CLI at all (the guards only concern increment files), and
+ * PreToolUse for Bash prints `{}` unless the project opted into the Jev command
+ * guard with a `.specweave/state/jev-guard.enabled` marker.
  */
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
@@ -62,6 +64,34 @@ function isPrivateOwnedFile(file) {
 
 const event = process.argv[2] ?? '';
 
+/** Opt-in marker for the Jev Bash guard, searched upward from cwd / project dir. */
+const JEV_GUARD_MARKER = path.join('.specweave', 'state', 'jev-guard.enabled');
+const JEV_GUARD_MAX_DEPTH = 8;
+
+function hasJevGuardMarker(input) {
+  const starts = [typeof input.cwd === 'string' ? input.cwd : process.cwd(), process.env.CLAUDE_PROJECT_DIR];
+  for (const start of starts) {
+    if (!start) continue;
+    let current;
+    try {
+      current = path.resolve(start);
+    } catch {
+      continue;
+    }
+    for (let depth = 0; depth < JEV_GUARD_MAX_DEPTH; depth++) {
+      try {
+        if (existsSync(path.join(current, JEV_GUARD_MARKER))) return true;
+      } catch {
+        break;
+      }
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  }
+  return false;
+}
+
 function inactiveOutput() {
   if (event === 'session-start') {
     return {
@@ -123,7 +153,12 @@ function normalizeInput(raw) {
         filePath = ti.file_path;
       }
       if (typeof input.cwd === 'string') input.cwd = input.cwd.replace(/\\/g, '/');
-      const skip = event === 'pre-tool-use' && !filePath.includes('.specweave/increments/');
+      const tool = typeof input.tool_name === 'string' ? input.tool_name : '';
+      const skip =
+        event === 'pre-tool-use' &&
+        (tool === 'Bash'
+          ? !hasJevGuardMarker(input)
+          : !filePath.includes('.specweave/increments/'));
       return { raw: JSON.stringify(input), skip };
     }
   } catch {