@ashlr/hub 2.2.0

package/dist/core/spec/spec-store.d.ts

@@ -0,0 +1,62 @@
+/**
+ * spec-store.ts — M12: First-class versioned END-STATE SPEC artifacts.
+ *
+ * Specs are markdown documents with a structured sidecar JSON (SpecArtifact).
+ * Versioning is NEVER destructive: refining produces v+1, never overwrites.
+ *
+ * Storage layout:
+ *   <project>/.ashlr/specs/<slug>-v<N>.md    ← markdown body
+ *   <project>/.ashlr/specs/<slug>-v<N>.json  ← SpecArtifact sidecar
+ *
+ * When no project is given, defaults to ~/.ashlr/specs (global store).
+ */
+import type { SpecArtifact, AshlrConfig } from '../types.js';
+/**
+ * Returns the absolute path to the specs directory for a given project.
+ * - When `project` is given: `<project>/.ashlr/specs`
+ * - Otherwise (global): `~/.ashlr/specs`
+ * Creates the directory on demand (mkdirSync recursive).
+ */
+export declare function specsDir(project?: string): string;
+/**
+ * List all specs in the given project (or global), returning the NEWEST
+ * version of each spec id, sorted by updatedAt descending.
+ */
+export declare function listSpecs(project?: string): SpecArtifact[];
+/**
+ * Load the HIGHEST version of a spec by id.
+ * Returns `{ meta, body }` or null if not found / unreadable.
+ *
+ * Search order (highest version across all readable dirs wins):
+ *   1. ~/.ashlr/specs           (global store)
+ *   2. <cwd>/.ashlr/specs       (project store when run from the project dir)
+ *   3. <project>/.ashlr/specs   (explicit --project hint, when given)
+ *
+ * The optional `project` hint lets `spec show`/`refine` find a project-scoped
+ * spec without having to `cd` into the project first (symmetry with new/list).
+ */
+export declare function loadSpec(id: string, project?: string): {
+    meta: SpecArtifact;
+    body: string;
+} | null;
+/**
+ * Author a new spec from a goal string.
+ *
+ * Uses the LOCAL-first model provider to draft a structured end-state spec
+ * with sections: Context / North Star / Operating Principles / Pillars /
+ * Roadmap / Verification. Persists `<slug>-v1.md` + sidecar `<slug>-v1.json`.
+ *
+ * The model call is BOUNDED (small output budget). Never throws.
+ */
+export declare function authorSpec(goal: string, cfg: AshlrConfig, opts?: {
+    project?: string;
+    allowCloud?: boolean;
+}): Promise<SpecArtifact>;
+/**
+ * Refine an existing spec by id: reads the current highest version, calls the
+ * model with the refinement note, writes v+1 (NEVER destructive — never
+ * overwrites prior versions).
+ *
+ * Returns the new SpecArtifact (v+1). Never throws.
+ */
+export declare function refineSpec(id: string, note: string, cfg: AshlrConfig, project?: string): Promise<SpecArtifact>;

package/dist/core/spec/spec-store.js

@@ -0,0 +1,359 @@
+/**
+ * spec-store.ts — M12: First-class versioned END-STATE SPEC artifacts.
+ *
+ * Specs are markdown documents with a structured sidecar JSON (SpecArtifact).
+ * Versioning is NEVER destructive: refining produces v+1, never overwrites.
+ *
+ * Storage layout:
+ *   <project>/.ashlr/specs/<slug>-v<N>.md    ← markdown body
+ *   <project>/.ashlr/specs/<slug>-v<N>.json  ← SpecArtifact sidecar
+ *
+ * When no project is given, defaults to ~/.ashlr/specs (global store).
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { getActiveClient } from '../run/provider-client.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Char cap for spec body injected into a refinement prompt. */
+const REFINE_BODY_CAP = 8_000;
+// ---------------------------------------------------------------------------
+// Directory helpers
+// ---------------------------------------------------------------------------
+/**
+ * Returns the absolute path to the specs directory for a given project.
+ * - When `project` is given: `<project>/.ashlr/specs`
+ * - Otherwise (global): `~/.ashlr/specs`
+ * Creates the directory on demand (mkdirSync recursive).
+ */
+export function specsDir(project) {
+    const dir = project
+        ? path.join(project, '.ashlr', 'specs')
+        : path.join(os.homedir(), '.ashlr', 'specs');
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+// ---------------------------------------------------------------------------
+// ID / slug helpers
+// ---------------------------------------------------------------------------
+/**
+ * Derive a stable slug from a goal string:
+ * lowercase, words joined with hyphens, max 48 chars, alphanumeric + hyphens only.
+ */
+function slugify(goal) {
+    return goal
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .trim()
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .slice(0, 48)
+        .replace(/-$/, '');
+}
+/**
+ * Generate a stable spec id from a goal. The id is the slug + a short hash
+ * so two similar goals don't silently collide.
+ */
+function generateSpecId(goal) {
+    const slug = slugify(goal);
+    const hash = crypto
+        .createHash('sha256')
+        .update(goal)
+        .digest('hex')
+        .slice(0, 6);
+    return `${slug}-${hash}`;
+}
+// ---------------------------------------------------------------------------
+// File-path helpers
+// ---------------------------------------------------------------------------
+function mdPath(dir, id, version) {
+    return path.join(dir, `${id}-v${version}.md`);
+}
+function jsonPath(dir, id, version) {
+    return path.join(dir, `${id}-v${version}.json`);
+}
+// ---------------------------------------------------------------------------
+// Persistence helpers
+// ---------------------------------------------------------------------------
+/** Write sidecar JSON atomically (write-then-rename). */
+function saveMeta(dir, meta) {
+    const target = jsonPath(dir, meta.id, meta.version);
+    const tmp = `${target}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(meta, null, 2), 'utf8');
+    fs.renameSync(tmp, target);
+}
+/** Write markdown body atomically. */
+function saveBody(filePath, body) {
+    const tmp = `${filePath}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, body, 'utf8');
+    fs.renameSync(tmp, filePath);
+}
+// ---------------------------------------------------------------------------
+// Spec listing / loading
+// ---------------------------------------------------------------------------
+/**
+ * List all specs in the given project (or global), returning the NEWEST
+ * version of each spec id, sorted by updatedAt descending.
+ */
+export function listSpecs(project) {
+    const dir = specsDir(project);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    // Collect all .json sidecars → parse → keep highest version per id
+    const byId = new Map();
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.json'))
+            continue;
+        const fullPath = path.join(dir, entry.name);
+        try {
+            const raw = fs.readFileSync(fullPath, 'utf8');
+            const meta = JSON.parse(raw);
+            if (!meta.id || typeof meta.version !== 'number')
+                continue;
+            const existing = byId.get(meta.id);
+            if (!existing || meta.version > existing.version) {
+                byId.set(meta.id, meta);
+            }
+        }
+        catch {
+            // Corrupt or partial file — skip silently
+        }
+    }
+    return Array.from(byId.values()).sort((a, b) => (b.updatedAt > a.updatedAt ? 1 : -1));
+}
+/**
+ * Load the HIGHEST version of a spec by id.
+ * Returns `{ meta, body }` or null if not found / unreadable.
+ *
+ * Search order (highest version across all readable dirs wins):
+ *   1. ~/.ashlr/specs           (global store)
+ *   2. <cwd>/.ashlr/specs       (project store when run from the project dir)
+ *   3. <project>/.ashlr/specs   (explicit --project hint, when given)
+ *
+ * The optional `project` hint lets `spec show`/`refine` find a project-scoped
+ * spec without having to `cd` into the project first (symmetry with new/list).
+ */
+export function loadSpec(id, project) {
+    // Try global, cwd, and (when given) the explicit project dir.
+    const candidates = [
+        path.join(os.homedir(), '.ashlr', 'specs'),
+        path.join(process.cwd(), '.ashlr', 'specs'),
+    ];
+    if (project) {
+        const projDir = path.join(project, '.ashlr', 'specs');
+        if (!candidates.includes(projDir))
+            candidates.push(projDir);
+    }
+    let best = null;
+    let bestDir = '';
+    for (const dir of candidates) {
+        if (!fs.existsSync(dir))
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith('.json'))
+                continue;
+            if (!entry.name.startsWith(id + '-v'))
+                continue;
+            const fullPath = path.join(dir, entry.name);
+            try {
+                const raw = fs.readFileSync(fullPath, 'utf8');
+                const meta = JSON.parse(raw);
+                if (meta.id !== id)
+                    continue;
+                if (!best || meta.version > best.version) {
+                    best = meta;
+                    bestDir = dir;
+                }
+            }
+            catch {
+                // skip
+            }
+        }
+    }
+    if (!best)
+        return null;
+    const bodyFile = mdPath(bestDir, best.id, best.version);
+    let body = '';
+    try {
+        body = fs.readFileSync(bodyFile, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    return { meta: best, body };
+}
+// ---------------------------------------------------------------------------
+// Model helpers
+// ---------------------------------------------------------------------------
+/** The structured system prompt for spec authoring. */
+const SPEC_SYSTEM_PROMPT = `You are an expert software architect and product strategist.
+Your task is to draft a structured END-STATE SPEC — a concrete, ambitious, grounded document
+describing the DESIRED END STATE of a software project or initiative.
+
+The spec MUST have exactly these sections (use level-2 markdown headings):
+
+## Context
+Who is building this, for whom, what problem it solves, current state.
+
+## North Star
+A single crisp sentence capturing the ultimate outcome. What does "done" look like?
+
+## Operating Principles
+3–6 guiding constraints and values (e.g. local-first, no-runtime-deps, safety-first).
+
+## Pillars
+3–5 major capability pillars / feature clusters with brief descriptions.
+
+## Roadmap
+Phases (Phase 1, Phase 2, …). Each phase: name, goal, 2–5 key deliverables.
+Keep concrete and achievable, not aspirational fluff.
+
+## Verification
+How will we know the spec is satisfied? 3–6 measurable acceptance criteria.
+
+RULES:
+- Be concrete, specific, and grounded. Avoid vague adjectives.
+- No marketing copy. No fluff. Prefer bullet points over prose.
+- Keep total length 600–1000 words. Quality over quantity.
+- Do NOT include section numbers or table of contents.
+- Return ONLY the markdown spec body — no preamble, no postamble.`;
+/** Build the user prompt for authoring a new spec. */
+function buildAuthorPrompt(goal) {
+    return `Draft an end-state spec for the following goal:\n\n> ${goal}\n\nReturn only the structured markdown spec body.`;
+}
+/** Build the user prompt for refining an existing spec. */
+function buildRefinePrompt(goal, version, body, note) {
+    const truncatedBody = body.length > REFINE_BODY_CAP ? body.slice(0, REFINE_BODY_CAP) + '\n\n[...truncated]' : body;
+    return (`You are refining an existing end-state spec (currently v${version}) for the goal:\n\n` +
+        `> ${goal}\n\n` +
+        `--- CURRENT SPEC ---\n${truncatedBody}\n--- END CURRENT SPEC ---\n\n` +
+        `Refinement note / change request:\n> ${note}\n\n` +
+        `Produce an improved v${version + 1} of the spec, incorporating the note. ` +
+        `Preserve the same six-section structure. Return only the updated markdown spec body.`);
+}
+/**
+ * Call the LOCAL-first model to produce a spec body string.
+ * Bounded to SPEC_MAX_TOKENS output. Never throws — returns a fallback stub on error.
+ */
+async function callModel(cfg, systemPrompt, userPrompt, allowCloud) {
+    try {
+        const client = await getActiveClient(cfg, { allowCloud });
+        const result = await client.chat([
+            { role: 'system', content: systemPrompt },
+            { role: 'user', content: userPrompt },
+        ]);
+        return {
+            content: result.content.trim(),
+            usage: result.usage,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Return a stub spec so spec-store never throws to the caller
+        const stub = buildStubSpec(userPrompt);
+        process.stderr.write(`[spec-store] model call failed (${msg}); returning stub spec\n`);
+        return { content: stub, usage: { tokensIn: 0, tokensOut: 0 } };
+    }
+}
+/** Minimal stub spec returned when no model is available. */
+function buildStubSpec(hint) {
+    return `## Context\n_No model available — fill in context manually._\n\n` +
+        `## North Star\n_Define the desired end state here._\n\n` +
+        `## Operating Principles\n- Local-first\n- No secrets in logs\n\n` +
+        `## Pillars\n- _Pillar 1_\n- _Pillar 2_\n\n` +
+        `## Roadmap\n### Phase 1\n- _Deliverable 1_\n\n` +
+        `## Verification\n- _Acceptance criterion 1_\n\n` +
+        `<!-- hint: ${hint.slice(0, 80)} -->`;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Author a new spec from a goal string.
+ *
+ * Uses the LOCAL-first model provider to draft a structured end-state spec
+ * with sections: Context / North Star / Operating Principles / Pillars /
+ * Roadmap / Verification. Persists `<slug>-v1.md` + sidecar `<slug>-v1.json`.
+ *
+ * The model call is BOUNDED (small output budget). Never throws.
+ */
+export async function authorSpec(goal, cfg, opts) {
+    const project = opts?.project ?? null;
+    const dir = specsDir(project ?? undefined);
+    const id = generateSpecId(goal);
+    const version = 1;
+    const now = new Date().toISOString();
+    // Check if v1 already exists for this id — if so, return it (idempotent)
+    const existing = loadSpec(id);
+    if (existing && existing.meta.version === 1) {
+        return existing.meta;
+    }
+    // Cloud allowance: when a caller EXPLICITLY passes opts.allowCloud, that
+    // decision OVERRIDES the chain-derived heuristic — so a caller (e.g. M28
+    // `goals plan` without --allow-cloud) can force local-only even when a cloud
+    // provider (anthropic) sits in the default providerChain. Only fall back to
+    // the chain heuristic when the caller did not express a preference.
+    const allowCloud = opts?.allowCloud ??
+        (cfg.models?.providerChain ?? []).some((p) => !['ollama', 'lmstudio', 'builtin'].includes(p));
+    const { content } = await callModel(cfg, SPEC_SYSTEM_PROMPT, buildAuthorPrompt(goal), allowCloud);
+    const bodyPath = mdPath(dir, id, version);
+    const meta = {
+        id,
+        goal,
+        version,
+        project,
+        path: bodyPath,
+        status: 'draft',
+        createdAt: now,
+        updatedAt: now,
+    };
+    saveBody(bodyPath, content);
+    saveMeta(dir, meta);
+    return meta;
+}
+/**
+ * Refine an existing spec by id: reads the current highest version, calls the
+ * model with the refinement note, writes v+1 (NEVER destructive — never
+ * overwrites prior versions).
+ *
+ * Returns the new SpecArtifact (v+1). Never throws.
+ */
+export async function refineSpec(id, note, cfg, project) {
+    const existing = loadSpec(id, project);
+    if (!existing) {
+        throw new Error(`spec-store: spec not found: ${id}`);
+    }
+    const { meta: currentMeta, body: currentBody } = existing;
+    const nextVersion = currentMeta.version + 1;
+    const now = new Date().toISOString();
+    const dir = specsDir(currentMeta.project ?? undefined);
+    // Determine cloud allowance from config
+    const allowCloud = (cfg.models?.providerChain ?? []).some((p) => !['ollama', 'lmstudio', 'builtin'].includes(p));
+    const { content } = await callModel(cfg, SPEC_SYSTEM_PROMPT, buildRefinePrompt(currentMeta.goal, currentMeta.version, currentBody, note), allowCloud);
+    const bodyPath = mdPath(dir, id, nextVersion);
+    const newMeta = {
+        ...currentMeta,
+        version: nextVersion,
+        path: bodyPath,
+        updatedAt: now,
+    };
+    saveBody(bodyPath, content);
+    saveMeta(dir, newMeta);
+    return newMeta;
+}
+//# sourceMappingURL=spec-store.js.map

package/dist/core/spec/spec-store.js.map

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

package/dist/core/swarm/gate.d.ts

@@ -0,0 +1,45 @@
+/**
+ * core/swarm/gate.ts — M17 escalation gate.
+ *
+ * Two pure, deterministic, never-throwing exports:
+ *   riskScan       — heuristic detection of destructive/outward ops in text
+ *   shouldEscalate — priority-ordered escalation kind selector
+ *
+ * Neither function has side-effects; the caller is responsible for persisting
+ * EscalationEvent records, setting status 'needs-approval', and stopping the
+ * swarm. No auto-approval path exists here.
+ */
+import type { EscalationReasonKind } from '../types.js';
+/**
+ * Scan `text` for destructive or outward-facing operation patterns.
+ *
+ * Returns `{ risky: true, reason }` on the first match, or
+ * `{ risky: false, reason: '' }` if no pattern matches.
+ *
+ * Pure, case-insensitive, never throws.
+ */
+export declare function riskScan(text: string): {
+    risky: boolean;
+    reason: string;
+};
+/**
+ * Determine whether an escalation is needed, and which kind.
+ *
+ * Priority order (highest → lowest):
+ *   tamper → verify-failed → over-budget → risk → low-confidence
+ *
+ * Returns the first applicable `EscalationReasonKind`, or `null` if none apply.
+ *
+ * PURE — no side-effects. The caller must:
+ *   1. Persist the EscalationEvent
+ *   2. Set swarm status to 'needs-approval'
+ *   3. STOP the swarm
+ * Never auto-approves; never throws.
+ */
+export declare function shouldEscalate(ctx: {
+    verifyFailed?: boolean;
+    overBudget?: boolean;
+    tamper?: boolean;
+    risk?: boolean;
+    lowConfidence?: boolean;
+}): EscalationReasonKind | null;

package/dist/core/swarm/gate.js

@@ -0,0 +1,114 @@
+/**
+ * core/swarm/gate.ts — M17 escalation gate.
+ *
+ * Two pure, deterministic, never-throwing exports:
+ *   riskScan       — heuristic detection of destructive/outward ops in text
+ *   shouldEscalate — priority-ordered escalation kind selector
+ *
+ * Neither function has side-effects; the caller is responsible for persisting
+ * EscalationEvent records, setting status 'needs-approval', and stopping the
+ * swarm. No auto-approval path exists here.
+ */
+const RISK_PATTERNS = [
+    // Filesystem destruction
+    { re: /rm\s+-[a-z]*r[a-z]*f|rm\s+-[a-z]*f[a-z]*r/i, reason: 'rm -rf (recursive force delete) detected' },
+    { re: /\brm\b.*--no-preserve-root/i, reason: 'rm --no-preserve-root detected' },
+    // Git destructive / outward ops
+    { re: /git\s+push\s+.*--force(?:-with-lease)?(?:\s|$)/i, reason: 'git push --force detected' },
+    { re: /git\s+push\s+.*-f(?:\s|$)/i, reason: 'git push -f detected' },
+    { re: /force.?push/i, reason: 'force-push pattern detected' },
+    { re: /git\s+reset\s+--hard/i, reason: 'git reset --hard detected' },
+    { re: /git\s+clean\s+.*-[a-z]*f/i, reason: 'git clean -f detected' },
+    // Deploy / release ops
+    // Deploy/release intent. Tightened to match an ACTUAL deploy ACTION rather
+    // than the bare noun, so benign goal text ("Implement a deployment pipeline
+    // module", "Add deployment docs", "Create a deploy script that prints
+    // instructions") does NOT escalate. We require one of:
+    //   • "deploy to <env>"        — e.g. "deploy to production"
+    //   • a deploy CLI token       — vercel/netlify/fly/wrangler/heroku/kubectl
+    //                                + deploy/apply/publish, in either order
+    //   • "git push" (covered by the force-push patterns above; bare push below)
+    // The previous bare-noun pattern over-fired on legitimate work (verified:
+    // "deployment pipeline configuration module" flagged), which — combined with
+    // the goal-risk approve flow — could strand benign tasks. False positives on
+    // softer noun mentions are now left to explicit deploy-action phrasing.
+    { re: /\bdeploy(?:s|ed|ing)?\s+to\s+\w/i, reason: 'deploy to <target> operation detected' },
+    { re: /\b(?:vercel|netlify|fly|flyctl|wrangler|heroku|kubectl|serverless|sst)\b[^\n]{0,40}\b(?:deploy|apply|publish|push|release)\b/i, reason: 'deploy CLI command detected' },
+    { re: /\b(?:deploy|publish|ship|release)\b[^\n]{0,30}\b(?:to\s+)?(?:prod|production|staging|live)\b/i, reason: 'deploy/release to environment detected' },
+    { re: /\bvercel\b.*--prod/i, reason: 'vercel --prod deployment detected' },
+    { re: /\bnpm\s+publish\b/i, reason: 'npm publish detected' },
+    // SQL destructive ops
+    { re: /\bDROP\s+(?:TABLE|DATABASE|SCHEMA|INDEX|VIEW)\b/i, reason: 'SQL DROP statement detected' },
+    { re: /\bTRUNCATE\s+TABLE\b/i, reason: 'SQL TRUNCATE TABLE detected' },
+    { re: /\bDELETE\s+FROM\b.*(?:WHERE\s+1|WHERE\s+true|;\s*$)/i, reason: 'potentially unbounded SQL DELETE detected' },
+    // Shell pipe executions (curl/wget | sh/bash)
+    { re: /(?:curl|wget)\b.*\|\s*(?:ba)?sh\b/i, reason: 'remote script execution (curl|sh) detected' },
+    { re: /\beval\s*\$\(/i, reason: 'eval $(...) shell injection pattern detected' },
+    // Dangerous permissions
+    { re: /\bchmod\s+(?:a\+[rwx]*|[0-7]*7[0-7][0-7])\b/i, reason: 'chmod 777 or world-writable permission detected' },
+    // Secret / credential exfiltration patterns
+    { re: /\bcurl\b.*(?:Authorization|Bearer|api.?key|secret|token|password|passwd|credential)/i, reason: 'potential credential exfiltration via curl detected' },
+    { re: /\bwget\b.*(?:Authorization|Bearer|api.?key|secret|token|password|passwd|credential)/i, reason: 'potential credential exfiltration via wget detected' },
+    { re: /(?:export|echo|print)\s+.*(?:SECRET|API_KEY|PASSWORD|TOKEN|PRIVATE_KEY)/i, reason: 'potential secret variable exposure detected' },
+    // Well-known credential identifiers paired with an EXPOSURE/EXFIL verb. The
+    // prior pattern flagged the bare identifier regardless of context, which
+    // over-fired on benign goals (verified: "Build a tokenizer for the API_KEY
+    // header field" flagged). We now require a read/print/send/leak-style verb
+    // near the identifier so handling-by-name is a signal but mere mention is not.
+    // (Direct exposure via export/echo/print is also covered by the pattern above,
+    // and exfil via curl/wget by the patterns above that.)
+    { re: /\b(?:print|echo|log|dump|leak|expose|reveal|send|post|upload|exfil(?:trate)?|cat|read|copy|email|curl|wget|fetch)\b[^\n]{0,40}\b(?:[A-Z][A-Z0-9]*_)*(?:API_KEY|SECRET_ACCESS_KEY|ACCESS_KEY_ID|SECRET_KEY|PRIVATE_KEY|AUTH_TOKEN|ACCESS_TOKEN)\b/i, reason: 'potential credential identifier exposure detected' },
+    { re: /\b(?:[A-Z][A-Z0-9]*_)*(?:API_KEY|SECRET_ACCESS_KEY|ACCESS_KEY_ID|SECRET_KEY|PRIVATE_KEY|AUTH_TOKEN|ACCESS_TOKEN)\b[^\n]{0,30}\b(?:to\s+)?(?:stdout|console|file|disk|remote|endpoint|url|http)\b/i, reason: 'potential credential identifier exposure detected' },
+    { re: /\bcat\b.*(?:\.env|id_rsa|id_ed25519|\.pem|\.key)\b/i, reason: 'potential secret file read detected' },
+    { re: /\bcp\b.*(?:id_rsa|id_ed25519|\.pem|\.key)\b/i, reason: 'potential private key copy detected' },
+];
+/**
+ * Scan `text` for destructive or outward-facing operation patterns.
+ *
+ * Returns `{ risky: true, reason }` on the first match, or
+ * `{ risky: false, reason: '' }` if no pattern matches.
+ *
+ * Pure, case-insensitive, never throws.
+ */
+export function riskScan(text) {
+    try {
+        for (const { re, reason } of RISK_PATTERNS) {
+            if (re.test(text)) {
+                return { risky: true, reason };
+            }
+        }
+        return { risky: false, reason: '' };
+    }
+    catch {
+        // Defensive: should never reach here given static regexes, but never throw.
+        return { risky: false, reason: '' };
+    }
+}
+/**
+ * Determine whether an escalation is needed, and which kind.
+ *
+ * Priority order (highest → lowest):
+ *   tamper → verify-failed → over-budget → risk → low-confidence
+ *
+ * Returns the first applicable `EscalationReasonKind`, or `null` if none apply.
+ *
+ * PURE — no side-effects. The caller must:
+ *   1. Persist the EscalationEvent
+ *   2. Set swarm status to 'needs-approval'
+ *   3. STOP the swarm
+ * Never auto-approves; never throws.
+ */
+export function shouldEscalate(ctx) {
+    if (ctx.tamper)
+        return 'tamper';
+    if (ctx.verifyFailed)
+        return 'verify-failed';
+    if (ctx.overBudget)
+        return 'over-budget';
+    if (ctx.risk)
+        return 'risk';
+    if (ctx.lowConfidence)
+        return 'low-confidence';
+    return null;
+}
+//# sourceMappingURL=gate.js.map

package/dist/core/swarm/gate.js.map

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

package/dist/core/swarm/planner.d.ts

@@ -0,0 +1,32 @@
+/**
+ * core/swarm/planner.ts — M12 swarm planner.
+ *
+ * planSwarm({goal, specBody?}, cfg): Promise<SwarmPlan>
+ *
+ * Decomposes a goal (+ optional spec body) into a phased SwarmPlan via a
+ * single bounded model call (LOCAL-first). Guardrails:
+ *  - Single model call; never throws — all failures fall back to a sensible
+ *    default plan.
+ *  - Tasks per phase capped at <= 6; total tasks capped at <= 18.
+ *  - BUILD-phase tasks are independent (no intra-build deps); later phases
+ *    carry deps on the tasks from the prior phase.
+ *  - IDs are stable slugs: scaffold-1, build-1..N, integrate-1, verify-1, review-1.
+ */
+import type { SwarmPlan, AshlrConfig } from '../types.js';
+/**
+ * Decompose a goal (+ optional spec body) into a phased SwarmPlan.
+ *
+ * CONTRACT (from docs/contracts/CONTRACT-M12.md):
+ *   planSwarm(input: { goal: string; specBody?: string }, cfg: AshlrConfig): Promise<SwarmPlan>
+ *
+ * Guardrails:
+ *  - Single bounded model call; never throws.
+ *  - Tasks per phase <= 6; total tasks <= 18.
+ *  - BUILD-phase tasks are independent (deps = scaffold tasks only).
+ *  - Falls back to a sensible default plan on any failure.
+ *  - LOCAL-first (opts.allowCloud defaults false).
+ */
+export declare function planSwarm(input: {
+    goal: string;
+    specBody?: string;
+}, cfg: AshlrConfig): Promise<SwarmPlan>;