continuous-improvement 3.12.3 → 3.15.0

package/lib/gateguard-state.mjs

@@ -2,20 +2,25 @@
  * Gateguard per-session state.
  *
  * State file: <sessionDir>/gateguard-session.json. sessionDir resolves to
- * GATEGUARD_SESSION_DIR (env override, used by tests) or
- * ~/.claude/instincts/<projectHash>/ in production.
+ * GATEGUARD_SESSION_DIR (env override, used by tests), or in production to
+ * ~/.claude/instincts/<projectHash>/sessions/<sessionId>/ when the hook passes
+ * the stdin session_id, falling back to ~/.claude/instincts/<projectHash>/ when
+ * no session id is available. Per-session scoping is what stops the clearance
+ * cap from bleeding across concurrent same-day sessions on a multi-Claude host.
  *
- * V1 limitations (documented for honesty, not mitigated in code):
+ * Limitations and guarantees:
  * - Honor system: clearance is granted whenever the agent sets
  *   `_gateguard_facts_presented: true` in tool_input or has a prior per-file
  *   marker. The hook cannot verify that real investigation occurred.
  * - State-file deletion: rm'ing the state file resets every gate in the
- *   session. Defensible because the session itself is the trust boundary;
- *   the cap below limits cumulative damage.
+ *   session. Defensible because the session is the trust boundary — and with
+ *   per-session scoping that boundary is now real, not just asserted.
+ * - Self-heal: loadState treats a file older than STATE_TTL_MS (or one with an
+ *   unparseable created_at) as empty, so a stale gate never needs a manual rm.
  * - Concurrency: two parallel hook invocations can race the read+write.
  *   Acceptable trade-off vs OS-specific atomic-rename complexity on Windows.
- * - Cap: MAX_CLEARED_FILES caps the number of distinct files a single
- *   session can clear, bounding stuck-loop / rogue-agent damage.
+ * - Cap: MAX_CLEARED_FILES caps the distinct files ONE session can clear,
+ *   bounding stuck-loop / rogue-agent damage without affecting other sessions.
  */
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -23,14 +28,36 @@ import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import { join } from "node:path";
 export const MAX_CLEARED_FILES = 50;
-export function resolveSessionDir() {
+// A clearance file whose created_at is older than this self-heals to empty on
+// the next load, so a stale gate never needs a manual rm. Long enough not to
+// reset an active session mid-work; the real cross-session fix is the
+// per-session dir in resolveSessionDir below.
+export const STATE_TTL_MS = 12 * 60 * 60 * 1000; // 12h
+// The root that holds every project's gateguard + instinct state. The MCP
+// clearance route uses this to bound a caller-supplied state_path to this tree
+// so a hostile argument can't turn the clear into an arbitrary-write primitive.
+export function resolveInstinctsRoot() {
+    const home = process.env.HOME || process.env.USERPROFILE || homedir();
+    return join(home, ".claude", "instincts");
+}
+export function resolveSessionDir(sessionId) {
     const fromEnv = process.env.GATEGUARD_SESSION_DIR;
     if (fromEnv)
         return fromEnv;
-    const home = process.env.HOME || process.env.USERPROFILE || homedir();
     const projectRoot = resolveProjectRoot();
     const projectHash = createHash("sha256").update(canonicalizeProjectRoot(projectRoot)).digest("hex").slice(0, 12);
-    return join(home, ".claude", "instincts", projectHash);
+    const base = join(resolveInstinctsRoot(), projectHash);
+    const scoped = sanitizeSessionId(sessionId);
+    return scoped ? join(base, "sessions", scoped) : base;
+}
+// A session id flows into a directory name. Strip anything outside a safe
+// alphabet so a hostile or malformed id can't traverse (`../`) or break the
+// path, and cap the length. Returns "" for an absent/empty id, which the caller
+// treats as "no session" — the legacy unscoped dir, preserving back-compat.
+function sanitizeSessionId(sessionId) {
+    if (!sessionId)
+        return "";
+    return sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64);
 }
 function resolveProjectRoot() {
     const fromEnv = process.env.CLAUDE_PROJECT_DIR;
@@ -49,21 +76,43 @@ function resolveProjectRoot() {
     }
     return "global";
 }
+function freshState() {
+    return { created_at: new Date().toISOString(), cleared_files: {} };
+}
+// A clearance file self-heals to empty once it ages out of STATE_TTL_MS, so a
+// stale gate never needs a manual rm. An unparseable created_at fails closed
+// (treated as expired) rather than living forever as a never-resetting gate.
+function isExpired(createdAt) {
+    const created = Date.parse(createdAt);
+    if (Number.isNaN(created))
+        return true;
+    return Date.now() - created > STATE_TTL_MS;
+}
 export function loadState(sessionDir) {
     const path = join(sessionDir, "gateguard-session.json");
     if (!existsSync(path)) {
-        return { created_at: new Date().toISOString(), cleared_files: {} };
+        return freshState();
     }
     try {
         const raw = readFileSync(path, "utf8");
         const parsed = JSON.parse(raw);
+        // Absent created_at is treated as expired (fail closed), like an unparseable
+        // one — never a never-resetting gate. On expiry we persist the new epoch
+        // immediately so the cap re-applies from zero on the very next load;
+        // otherwise every load before the next clear would independently reset and a
+        // TTL-crossing session could clear well past MAX_CLEARED_FILES.
+        if (!parsed.created_at || isExpired(parsed.created_at)) {
+            const reset = freshState();
+            saveState(sessionDir, reset);
+            return reset;
+        }
         return {
-            created_at: parsed.created_at ?? new Date().toISOString(),
+            created_at: parsed.created_at,
             cleared_files: parsed.cleared_files ?? {},
         };
     }
     catch {
-        return { created_at: new Date().toISOString(), cleared_files: {} };
+        return freshState();
     }
 }
 export function saveState(sessionDir, state) {

package/lib/goal-state.mjs

@@ -20,10 +20,14 @@ const STOPWORDS = new Set([
     "task", "goal", "plan", "work", "working", "build", "building", "code",
 ]);
 // 4 suits Latin/Cyrillic/Thai prose (Thai combining marks are now kept; see
-// extractKeywordsFromProse regex), but it silently drops most Korean words
-// (typically 2 chars). A script-aware floor for Korean is a logged follow-up
-// (see CLAUDE.md Deferred).
+// extractKeywordsFromProse regex). Korean Hangul words are typically 2-3 chars
+// but represent full concepts, so they get a script-aware floor of 2.
 const KEYWORD_MIN_LENGTH = 4;
+function keywordMinLengthFor(word) {
+    if (/\p{Script=Hangul}/u.test(word))
+        return 2;
+    return KEYWORD_MIN_LENGTH;
+}
 const KEYWORD_CAP = 20;
 const DEFAULT_WINDOW = 30;
 const DEFAULT_THRESHOLD = 0.3;
@@ -61,7 +65,7 @@ export function extractKeywordsFromProse(prose) {
     const out = [];
     for (const raw of prose.toLowerCase().split(/[^\p{L}\p{N}\p{M}]+/u)) {
         const word = raw.trim();
-        if (word.length < KEYWORD_MIN_LENGTH)
+        if (word.length < keywordMinLengthFor(word))
             continue;
         if (/^\p{N}+$/u.test(word))
             continue;

package/lib/hook-pack-gate.mjs

@@ -0,0 +1,65 @@
+// hook-pack-gate.mts — Pure decision core for the enforcing-hook pack (v1).
+//
+// No I/O. Given a raw Bash command string, the resolved current branch, the
+// staged-file count, and the operator's mode, decide allow / warn / block.
+// The hook (src/hooks/hook-pack.mts) wires stdin + git subprocess calls around
+// these functions; keeping them pure lets the unit tests cover every branch
+// without spawning anything. Lives in lib/ so tests can import it (the
+// test-imports-only invariant forbids importing from hooks/).
+//
+// Fail-open by construction: callers pass safe defaults (null branch, 0 staged)
+// on any failure, and an unrecognized mode resolves to warn.
+export const COMMIT_FILE_LIMIT = 15;
+const ALLOW = { action: "allow", reason: "" };
+export function parseMode(raw) {
+    const v = (raw ?? "warn").trim().toLowerCase();
+    return v === "block" || v === "off" ? v : "warn";
+}
+// Match `git push` / `git commit` at the start of the command or immediately
+// after a shell separator (newline, ;, |, &). This deliberately does NOT match
+// a mention like `echo git push`, where git is an argument, not the command.
+export function classifyCommand(command) {
+    if (/(?:^|[\n;|&])\s*git\s+push\b/.test(command))
+        return "push";
+    if (/(?:^|[\n;|&])\s*git\s+commit\b/.test(command))
+        return "commit";
+    return "other";
+}
+export function isProtectedBranch(branch) {
+    return branch === "main" || branch === "master" || /^release\//.test(branch);
+}
+// Extract the explicit destination branch of a `git push`, or null when none is
+// given (the caller should then fall back to the current branch). Handles
+// `git push <remote> <branch>`, `git push -u <remote> <branch>`, and refspecs
+// like `HEAD:main` (destination after the colon).
+function parsePushTarget(command) {
+    const tokens = command.split(/\s+/).filter(Boolean);
+    const pushIdx = tokens.findIndex((t, i) => t === "push" && tokens[i - 1] === "git");
+    if (pushIdx === -1)
+        return null;
+    const operands = tokens.slice(pushIdx + 1).filter((t) => !t.startsWith("-"));
+    // operands[0] is the remote; operands[1] is the refspec. Fewer than two means
+    // no explicit branch (e.g. `git push` or `git push origin`).
+    if (operands.length < 2)
+        return null;
+    const refspec = operands[1];
+    return refspec.includes(":") ? (refspec.split(":").pop() ?? null) : refspec;
+}
+export function evaluatePush(command, currentBranch) {
+    if (/(?:^|\s)--dry-run\b/.test(command))
+        return { gated: false, branch: null };
+    const branch = parsePushTarget(command) ?? currentBranch;
+    if (!branch)
+        return { gated: false, branch: null };
+    return { gated: isProtectedBranch(branch), branch };
+}
+export function evaluateCommitSize(command, stagedCount) {
+    if (/(?:^|\s)--amend\b/.test(command))
+        return { gated: false };
+    return { gated: stagedCount > COMMIT_FILE_LIMIT };
+}
+export function decide(mode, gated, reason) {
+    if (!gated || mode === "off")
+        return ALLOW;
+    return { action: mode === "block" ? "block" : "warn", reason };
+}

package/lib/install-targets.mjs

@@ -0,0 +1,121 @@
+/**
+ * Multi-platform install targets for the 7-Laws skill.
+ *
+ * Pure planning layer — no filesystem access. The installer
+ * (src/bin/install.mts) feeds in the SKILL.md text plus a reader callback and
+ * executes the returned write plan against the project root. Keeping this
+ * pure lets the per-target contracts be unit-tested without temp dirs.
+ *
+ * v1 contract (docs/plans/2026-06-11-multi-platform-installer.md):
+ * - Non-Claude targets receive the skill text only; hooks, the MCP server,
+ *   and instinct learning stay Claude Code-only and every plan says so.
+ * - Shared files (GEMINI.md, AGENTS.md, .rules, CONVENTIONS.md,
+ *   copilot-instructions.md) are merged through a managed block so existing
+ *   user content is never clobbered and reinstalls are idempotent.
+ * - Own-file targets (cursor, windsurf) are written whole.
+ */
+export const MANAGED_BEGIN = "<!-- continuous-improvement:begin (managed block — reinstall via `npx continuous-improvement install --target <name>`; edits inside are overwritten) -->";
+export const MANAGED_END = "<!-- continuous-improvement:end -->";
+const TARGET_SPECS = {
+    gemini: { label: "Gemini CLI", mode: "managed", relPath: "GEMINI.md" },
+    codex: { label: "Codex CLI (agents.md standard)", mode: "managed", relPath: "AGENTS.md" },
+    cursor: { label: "Cursor", mode: "whole", relPath: ".cursor/rules/continuous-improvement.mdc" },
+    windsurf: { label: "Windsurf", mode: "whole", relPath: ".windsurf/rules/continuous-improvement.md" },
+    zed: { label: "Zed", mode: "managed", relPath: ".rules" },
+    aider: { label: "Aider", mode: "managed", relPath: "CONVENTIONS.md" },
+    copilot: { label: "GitHub Copilot", mode: "managed", relPath: ".github/copilot-instructions.md" },
+};
+export const TARGET_IDS = ["claude", ...Object.keys(TARGET_SPECS)];
+export function resolveTargets(csv) {
+    const targets = [];
+    const unknown = [];
+    for (const raw of csv.split(",")) {
+        const name = raw.trim().toLowerCase();
+        if (name === "")
+            continue;
+        if (!TARGET_IDS.includes(name)) {
+            if (!unknown.includes(name))
+                unknown.push(name);
+            continue;
+        }
+        if (!targets.includes(name))
+            targets.push(name);
+    }
+    return { targets, unknown };
+}
+export function stripFrontmatter(skillMd) {
+    if (!skillMd.startsWith("---\n") && !skillMd.startsWith("---\r\n"))
+        return skillMd;
+    const close = skillMd.indexOf("\n---", 3);
+    if (close === -1)
+        return skillMd;
+    const afterClose = skillMd.indexOf("\n", close + 1);
+    if (afterClose === -1)
+        return "";
+    return skillMd.slice(afterClose + 1).replace(/^\s*\n/, "");
+}
+export function mergeManagedBlock(existing, block) {
+    if (existing === null || existing.trim() === "") {
+        return `${block}\n`;
+    }
+    const beginAt = existing.indexOf(MANAGED_BEGIN);
+    const endAt = existing.indexOf(MANAGED_END);
+    if (beginAt !== -1 && endAt !== -1 && endAt > beginAt) {
+        const before = existing.slice(0, beginAt);
+        const after = existing.slice(endAt + MANAGED_END.length);
+        return `${before}${block}${after}`;
+    }
+    return `${existing.trimEnd()}\n\n${block}\n`;
+}
+function renderManagedBlock(skillMd) {
+    return `${MANAGED_BEGIN}\n${stripFrontmatter(skillMd).trim()}\n${MANAGED_END}`;
+}
+function renderCursorRule(skillMd) {
+    return [
+        "---",
+        "description: 7 Laws of AI Agent Discipline — continuous-improvement framework",
+        "alwaysApply: true",
+        "---",
+        "",
+        stripFrontmatter(skillMd).trim(),
+        "",
+    ].join("\n");
+}
+const AIDER_CONF_PATH = ".aider.conf.yml";
+const AIDER_MINIMAL_CONF = [
+    "# Written by `npx continuous-improvement install --target aider`.",
+    "# Loads the 7 Laws conventions into every Aider session.",
+    "read: [CONVENTIONS.md]",
+    "",
+].join("\n");
+export function planTargetWrites(targetId, skillMd, readExisting) {
+    if (targetId === "claude") {
+        throw new Error("claude is handled by the standard installer flow, not planTargetWrites");
+    }
+    const spec = TARGET_SPECS[targetId];
+    if (!spec) {
+        throw new Error(`Unknown install target: ${targetId}. Valid: ${TARGET_IDS.join(", ")}`);
+    }
+    const writes = [];
+    const notes = [
+        `${spec.label} gets the 7-Laws skill text only — hooks, the MCP server, and instinct learning are Claude Code-only.`,
+    ];
+    if (spec.mode === "whole") {
+        const content = targetId === "cursor" ? renderCursorRule(skillMd) : `${stripFrontmatter(skillMd).trim()}\n`;
+        writes.push({ relPath: spec.relPath, content });
+    }
+    else {
+        const block = renderManagedBlock(skillMd);
+        writes.push({ relPath: spec.relPath, content: mergeManagedBlock(readExisting(spec.relPath), block) });
+    }
+    if (targetId === "aider") {
+        const existingConf = readExisting(AIDER_CONF_PATH);
+        if (existingConf === null) {
+            writes.push({ relPath: AIDER_CONF_PATH, content: AIDER_MINIMAL_CONF });
+        }
+        else {
+            notes.push(`${AIDER_CONF_PATH} already exists — add CONVENTIONS.md to its \`read:\` list yourself (e.g. \`read: [CONVENTIONS.md]\`); the installer never rewrites an existing conf.`);
+        }
+    }
+    return { notes, writes };
+}

package/lib/plan-review-packet.mjs

@@ -0,0 +1,96 @@
+/**
+ * plan-review-packet: turn a plan doc into a commentable review packet.
+ *
+ * Pure markdown transform — no IO. Splits a `docs/plans/*.md` plan into
+ * anchored sections, extracts a TLDR, and renders a packet a reviewer can
+ * comment on inline (one `> Comment (R#):` slot per section).
+ */
+const TLDR_HEADINGS = new Set(["goal", "summary", "overview", "tldr"]);
+const HEADING_RE = /^(#{1,6})\s+(.*\S)\s*$/;
+function normalize(markdown) {
+    return markdown.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+/** Split a plan into reviewable level-2/3 sections, each with a stable [R#] anchor. */
+export function splitSections(markdown) {
+    const lines = normalize(markdown).split("\n");
+    const sections = [];
+    let current = null;
+    let counter = 0;
+    const flush = () => {
+        if (!current)
+            return;
+        counter += 1;
+        sections.push({
+            heading: current.heading,
+            level: current.level,
+            anchor: `R${counter}`,
+            body: current.body.join("\n").trim(),
+        });
+        current = null;
+    };
+    for (const line of lines) {
+        const match = HEADING_RE.exec(line);
+        const level = match ? match[1].length : 0;
+        if (level === 1) {
+            flush();
+        }
+        else if (level === 2 || level === 3) {
+            flush();
+            current = { heading: match[2].trim(), level, body: [] };
+        }
+        else if (current) {
+            current.body.push(line);
+        }
+    }
+    flush();
+    return sections;
+}
+/** First non-empty, non-heading paragraph of a block of markdown. */
+function firstParagraph(text) {
+    for (const block of text.split(/\n\s*\n/)) {
+        const kept = block
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0 && !/^#{1,6}(\s|$)/.test(l));
+        if (kept.length > 0)
+            return kept.join("\n");
+    }
+    return "";
+}
+/** Extract a one-glance TLDR: a Goal/Summary/Overview section, else the first paragraph. */
+export function extractTldr(markdown) {
+    const goal = splitSections(markdown).find((s) => TLDR_HEADINGS.has(s.heading.trim().toLowerCase()));
+    if (goal)
+        return firstParagraph(goal.body);
+    return firstParagraph(normalize(markdown));
+}
+function extractTitle(markdown) {
+    for (const line of normalize(markdown).split("\n")) {
+        const match = /^#\s+(.*\S)\s*$/.exec(line);
+        if (match)
+            return match[1].trim();
+    }
+    return "Plan Review";
+}
+/** Render a commentable review packet from a plan doc. */
+export function buildReviewPacket(markdown, options = {}) {
+    const title = extractTitle(markdown);
+    const tldr = extractTldr(markdown);
+    const sections = splitSections(markdown);
+    const out = [`# Review packet: ${title}`, ""];
+    if (options.source)
+        out.push(`Source: ${options.source}`);
+    out.push(`TLDR: ${tldr || "(none — skim the sections below)"}`, "");
+    out.push("> How to comment: reply under each `> Comment (R#):` line. The `[R#]` anchors are stable references you can cite back.", "", "---", "");
+    if (sections.length === 0) {
+        out.push("_No reviewable sections found in this plan._", "");
+        return out.join("\n");
+    }
+    for (const section of sections) {
+        out.push(`${"#".repeat(section.level)} ${section.heading} [${section.anchor}]`, "");
+        if (section.body)
+            out.push(section.body, "");
+        out.push(`> Comment (${section.anchor}):`, "");
+    }
+    return out.join("\n");
+}

package/lib/plugin-metadata.mjs

@@ -26,7 +26,7 @@ const KEYWORDS = [
     "transcript-linter",
 ];
 const CLAUDE_PLUGIN_CATEGORY = "productivity";
-const SHARED_PLUGIN_DESCRIPTION = "Makes Claude Code reason harder, recall past corrections, and learn from every session so its competence compounds run over run. The Mulahazah engine turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time — no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 25 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.";
+const SHARED_PLUGIN_DESCRIPTION = "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 25 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.";
 // Four vendored upstream companions registered alongside the CI plugin.
 // Each entry points at a pinned-SHA snapshot under third-party/<name>/.
 // See third-party/MANIFEST.md for refresh recipes and per-snapshot
@@ -143,6 +143,10 @@ const BEGINNER_TOOL_ENTRIES = [
                     type: "string",
                     description: "A single file path to clear (alternative to file_paths)",
                 },
+                state_path: {
+                    type: "string",
+                    description: "State-file path from the GateGuard block reason (the session-scoped gateguard-session.json). Pass it verbatim so the clearance lands in the session the hook is reading; it must resolve inside ~/.claude/instincts/. Omitting it falls back to the unscoped canonical dir — safe only in legacy (no session id) contexts; when the hook is session-scoped, omitting it writes to the wrong dir and the retry will still block.",
+                },
             },
             required: [],
         },
@@ -373,10 +377,16 @@ const EXPERT_TOOL_ENTRIES = [
             required: ["id"],
         },
     },
+    {
+        name: "ci_distill_from_workflow",
+        description: "Draft a reusable instinct from the most recent completed-and-verified native Workflow run in this project's observation feed. A Workflow script is an authored recipe, so a single run whose output passed verification is enough — unlike ci_distill_candidates, which needs a pattern repeated across sessions. Writes a DRAFT to drafts/ (a skeleton you edit); it changes no behavior until promoted with ci_distill_promote. Returns a message when no verified workflow run is found.",
+        manifestWhat: "Draft a reusable instinct from a verified Workflow run",
+        inputSchema: { type: "object", properties: {}, required: [] },
+    },
 ];
 const MODE_METADATA = {
     beginner: {
-        description: "Beginner mode: see what your agent learned, list its instincts, and request a session reflection. Bundles four grounding skills (gateguard, para-memory-files, tdd-workflow, verification-loop) so research, memory, tests, and verification happen by default — every edit starts from facts, not guesses.",
+        description: "Beginner mode: see what your agent learned, list its instincts, and request a session reflection. Bundles three grounding skills (gateguard, tdd-workflow, verification-loop) so research, memory, tests, and verification happen by default — every edit starts from facts, not guesses.",
         hooks: ["PreToolUse", "PostToolUse", "UserPromptSubmit"],
         hookDescription: "Silently captures every tool call as observations and routes prompts to the matching skill via the route table. Lightweight and non-blocking.",
     },
@@ -457,6 +467,11 @@ export function getPluginHooksConfig() {
         command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/companion-preference.mjs\"",
         timeout: 5,
     };
+    const hookPackCommand = {
+        type: "command",
+        command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/hook-pack.mjs\"",
+        timeout: 5,
+    };
     const observeCommand = {
         type: "command",
         command: "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/observe.sh\"",
@@ -501,6 +516,12 @@ export function getPluginHooksConfig() {
             // through with no output.
             PreToolUse: [
                 { hooks: [gateguardCommand, companionPreferenceCommand] },
+                // hook-pack gates Bash `git push` to protected branches and oversized
+                // `git commit`s. The "Bash" matcher scopes it off the hot path for all
+                // non-Bash tools, so the two-subprocess note above still holds for
+                // Edit/Read/etc. Warn-default (CLAUDE_CI_HOOKPACK_GATE) — never blocks
+                // until the operator opts in.
+                { matcher: "Bash", hooks: [hookPackCommand] },
             ],
             PostToolUse: [{ hooks: [observeCommand] }],
             UserPromptSubmit: [{ hooks: [routePromptCommand, recallBriefingCommand] }],

package/lib/skill-distill.mjs

@@ -220,3 +220,144 @@ export function formatCandidates(candidates, limit = 10) {
     }
     return lines.join("\n");
 }
+// ── Workflow-run → instinct bridge ───────────────────────────────────────────
+// A native Workflow run (Opus 4.8 orchestration / ultracode) is recorded in the
+// observation feed as a `tool: "Workflow"` row whose input_summary holds
+// {"script":"..."} — truncated (~500 chars), but meta.name/description/phases sit
+// at the head of the script and survive. The output_summary holds
+// {"status","runId",...} with status "async_launched": the feed captures the
+// LAUNCH, not the result. So a workflow's success is never read from the Workflow
+// row itself — it is inferred from a following verify-exit-0 in the same feed.
+//
+// Unlike findCandidates (which needs a pattern recurring across >=2 sessions to
+// reject coincidence), a Workflow script is an AUTHORED recipe: one verified run
+// warrants a draft, so the session/occurrence thresholds do not apply here.
+const WORKFLOW_TOOL = "Workflow";
+// Pull meta.name / meta.description / meta.phases[].title out of a (possibly
+// truncated) workflow script embedded as JSON in the observation input_summary.
+// Fail-closed: returns null unless a name is recoverable — a recipe with no
+// identity is never fabricated.
+function parseWorkflowScript(inputSummary) {
+    if (!inputSummary)
+        return null;
+    let script = "";
+    try {
+        const parsed = JSON.parse(inputSummary);
+        if (typeof parsed.script === "string")
+            script = parsed.script;
+    }
+    catch {
+        // input_summary may itself be truncated mid-JSON; recover the script field loosely.
+        const m = inputSummary.match(/"script"\s*:\s*"((?:[^"\\]|\\.)*)/);
+        if (m) {
+            try {
+                script = JSON.parse(`"${m[1]}"`);
+            }
+            catch {
+                script = m[1].replace(/\\n/g, "\n").replace(/\\"/g, '"').replace(/\\'/g, "'");
+            }
+        }
+    }
+    if (!script)
+        return null;
+    // Scope name/description to the meta head (text before `phases:`) so a phase
+    // object's own description: is never mistaken for meta.description; scope phase
+    // titles to the phases array literal so inline agent/step title: fields are not
+    // captured. The capture classes exclude quotes and newlines, so a hostile
+    // name/description cannot inject lines into the draft YAML — serializeDraft emits
+    // trigger as a quoted scalar.
+    const phasesAt = script.search(/\bphases\s*:/);
+    const metaHead = phasesAt >= 0 ? script.slice(0, phasesAt) : script;
+    const name = (metaHead.match(/\bname\s*:\s*['"]([^'"\r\n]+)['"]/) ?? [])[1] ?? "";
+    if (!name)
+        return null; // fail closed: no recipe identity
+    const description = (metaHead.match(/\bdescription\s*:\s*['"]([^'"\r\n]+)['"]/) ?? [])[1] ?? "";
+    const phasesBlock = (script.match(/\bphases\s*:\s*\[([^\]]*)\]/) ?? [])[1] ?? "";
+    const phases = [];
+    const phaseRe = /\btitle\s*:\s*['"]([^'"\r\n]+)['"]/g;
+    let pm;
+    while ((pm = phaseRe.exec(phasesBlock)) !== null)
+        phases.push(pm[1]);
+    return { name, description, phases };
+}
+// A single verify-exit-0 Bash row: a verify/test/build command whose output is not
+// failing. Mirrors classifyTrajectorySuccess's verify branch for one observation.
+function isVerifySuccessRow(observation) {
+    if ((observation.tool ?? "") !== "Bash")
+        return false;
+    const input = (observation.input_summary ?? "").toString();
+    const output = (observation.output_summary ?? "").toString();
+    return VERIFY_CMD.test(input) && !FAILURE_MARKER.test(output) && (output === "" || SUCCESS_MARKER.test(output));
+}
+/**
+ * Detect the most recent completed-and-verified Workflow run in an observation
+ * list. Returns null (fail closed) unless: a `tool: "Workflow"` row carries a
+ * parseable script with a name, AND a verify-exit-0 row follows it in the feed.
+ * The trailing verify is the only success signal — the Workflow row records the
+ * launch, never the result.
+ */
+export function workflowRunFromObservations(observations) {
+    let wfIndex = -1;
+    let meta = null;
+    for (let i = observations.length - 1; i >= 0; i -= 1) {
+        if ((observations[i].tool ?? "") !== WORKFLOW_TOOL)
+            continue;
+        const parsed = parseWorkflowScript((observations[i].input_summary ?? "").toString());
+        if (parsed) {
+            wfIndex = i;
+            meta = parsed;
+            break;
+        }
+    }
+    if (wfIndex === -1 || !meta)
+        return null;
+    const wfSession = (observations[wfIndex].session ?? "").toString();
+    // The verify that proves the run must follow the Workflow row in the SAME session.
+    // A verify from an unrelated later task (different session) does not count — the
+    // run is asynchronous, so an interleaved verify could otherwise falsely prove it.
+    let verifyCommand = "";
+    for (let i = wfIndex + 1; i < observations.length; i += 1) {
+        const row = observations[i];
+        if ((row.session ?? "").toString() !== wfSession)
+            continue;
+        if (isVerifySuccessRow(row)) {
+            verifyCommand = (row.input_summary ?? "").toString();
+            break;
+        }
+    }
+    if (!verifyCommand)
+        return null; // fail closed: no evidence the run's output landed
+    return { name: meta.name, description: meta.description, phases: meta.phases, verifyCommand };
+}
+/**
+ * Turn a verified Workflow run into a DRAFT instinct. The script's phase outline is
+ * a real skeleton (not a placeholder n-gram), but the human still edits the body
+ * before promoting. Reuses serializeDraft and the drafts/ ladder; the
+ * `draft-workflow-` id prefix marks the source and stays filesystem-safe.
+ */
+export function draftFromWorkflowRun(run) {
+    // Cap the slug so a hostile/huge meta.name cannot produce a path that trips
+    // ENAMETOOLONG on write; strip a trailing hyphen left by the cut.
+    const slug = slugifyNgram([run.name]).slice(0, 120).replace(/-+$/, "") || "workflow";
+    const phaseLine = run.phases.length > 0 ? run.phases.join(" → ") : "(phases not captured)";
+    const lines = [
+        `When this situation recurs, the workflow "${run.name}" handled it end to end and its output passed verification.`,
+        "",
+    ];
+    if (run.description)
+        lines.push(`Intent: ${run.description}`);
+    lines.push(`Phases: ${phaseLine}`);
+    lines.push(`Verified by: ${run.verifyCommand}`);
+    lines.push("", "Replace this with the concrete steps, preconditions, and gotchas before promoting —", "the phase outline is the skeleton, not the full recipe.");
+    return {
+        id: `draft-workflow-${slug}`,
+        trigger: `Auto-detected from a verified workflow run: ${run.name}${run.description ? ` — ${run.description}` : ""}`,
+        body: lines.join("\n"),
+        confidence: DRAFT_CONFIDENCE,
+        domain: "workflow",
+        ngram: run.phases.length > 0 ? run.phases : [run.name],
+        occurrences: 1,
+        sessions: 1,
+        outcome: "workflow-verified",
+    };
+}