@juzser/blacksmith 0.1.0

package/factory/orchestrator/dist/worktree.js

@@ -0,0 +1,207 @@
+import path from 'node:path';
+import { SmithError } from './errors.js';
+import { runGit as git } from './git.js';
+export class WorktreeError extends SmithError {
+}
+/** The task-id segment reserved for an epic's integration branch (smith/<epic>/integration) —
+ * never a real task. Exported for db/projector.ts's foldTasks() guard and epic.ts's
+ * runEpicVerdict(), both of which need to recognise `<epic>/integration` as non-task. */
+export const RESERVED_TASK_ID = 'integration';
+function localBranchExists(projectDir, branch) {
+    try {
+        git(projectDir, ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Best-effort default-branch detection: origin/HEAD symbolic ref first (the
+ * normal case after a clone), then whatever branch is currently checked out,
+ * then the conventional main/master names.
+ */
+function detectDefaultBranch(projectDir) {
+    try {
+        const ref = git(projectDir, ['symbolic-ref', 'refs/remotes/origin/HEAD']);
+        const name = ref.replace(/^refs\/remotes\/origin\//, '');
+        if (name && name !== ref)
+            return name;
+    }
+    catch {
+        // no origin/HEAD — fall through
+    }
+    try {
+        const current = git(projectDir, ['branch', '--show-current']);
+        if (current)
+            return current;
+    }
+    catch {
+        // detached or no commits yet — fall through
+    }
+    for (const candidate of ['main', 'master']) {
+        if (localBranchExists(projectDir, candidate))
+            return candidate;
+    }
+    throw new WorktreeError('worktree.default-branch-not-found', `Could not detect a default branch in ${projectDir}.`, { projectDir });
+}
+/**
+ * A task id without its own epic prefix: `epic-7/task-142` under epic-7 is
+ * `task-142`, and the same string under a *different* epic is left alone —
+ * the leading segment belongs to the id then, not to this epic.
+ *
+ * D-177: the branch name applied this strip and the directory did not, so one
+ * task id addressed one branch but two directories, and which one you got
+ * depended on how the operator happened to spell the id. Every shipped spec
+ * writes the qualified form; `listStale` derives the id it prints from the
+ * branch, so it always prints the bare form — and `worktree rm`, the verb the
+ * operator guide pairs it with, computed a path that did not exist for any
+ * worktree created from the qualified spelling. Four envkit worktrees sat on
+ * disk unreachable by the only verb meant to remove them.
+ *
+ * Deliberately not taskId.ts's single-argument `bareTaskId`, which drops the
+ * first segment whether or not it matches: a task id whose leading segment is
+ * some *other* epic keeps it, here and in the branch alike.
+ */
+function bareTaskId(epic, taskId) {
+    return taskId.startsWith(`${epic}/`) ? taskId.slice(epic.length + 1) : taskId;
+}
+/**
+ * Where a task's worktree lives: `<parent>/.wt/<project>/<bare-task-id>`, a
+ * SIBLING of the project rather than a child of it. Takes the epic for the
+ * same reason `taskBranchName` does — so both spellings of one id land in one
+ * place (D-177).
+ *
+ * D-42/P9-26: this used to be `path.join(projectDir, 'wt', taskId)`, and the
+ * cost was an epic whose six per-task lint gates were all green while
+ * `pnpm lint` at the integration root exited 1 without reading a source file.
+ * Every worktree is a full checkout carrying the project's own `biome.json`,
+ * so a tool that walks down from the project root found seven root configs
+ * and refused to run. From inside a worktree the siblings are not
+ * descendants, so no task gate could ever see the condition. Placing them
+ * outside the root kills the class outright: no root-walking tool can reach
+ * a path it would have to climb *up* to find, whatever tool comes next.
+ *
+ * D-40: absolute, always. `git worktree add` resolves a relative path against
+ * the git cwd — which is `projectDir` — so a relative `projectDir` used to
+ * put the checkout at `<root>/envkit/<root>/envkit/wt/<task>` while
+ * the returned path claimed otherwise. Resolving up front means the string
+ * this module returns is the string on disk.
+ */
+export function taskWorktreeDir(projectDir, epic, taskId) {
+    const project = path.resolve(projectDir);
+    return path.join(path.dirname(project), '.wt', path.basename(project), bareTaskId(epic, taskId));
+}
+/** `smith/<epic>/integration` — the one branch an epic assembles onto. Exported for
+ * integration.ts, which runs the check suite against it (D-42/P9-26). */
+export function integrationBranchName(epic) {
+    return `smith/${epic}/integration`;
+}
+/**
+ * `smith/<epic>/<bare-task-id>` — the branch convention, defined once.
+ *
+ * D-23/P9-12: exported because three places need to agree on it — this module
+ * (which creates the branch), taskEvents.ts's `task-added` (which declares it
+ * so the board can link to it before any worktree exists), and
+ * db/projector.ts's fallback for events logged before that payload field.
+ * Three hand-written copies of one string convention is one copy too many.
+ *
+ * A task_id already embeds its epic ("epic-7/task-142", findings.ts's
+ * convention) so strip that prefix before rejoining — concatenating epic +
+ * full task_id double-embeds it (smith/epic-7/epic-7/task-142). The CLI hands
+ * this whatever the operator typed, so both shapes really do arrive.
+ */
+export function taskBranchName(epic, taskId) {
+    return `smith/${epic}/${bareTaskId(epic, taskId)}`;
+}
+function ensureIntegrationBranch(projectDir, epic) {
+    const branch = integrationBranchName(epic);
+    if (!localBranchExists(projectDir, branch)) {
+        const defaultBranch = detectDefaultBranch(projectDir);
+        git(projectDir, ['branch', branch, defaultBranch]);
+    }
+    return branch;
+}
+/**
+ * Create a task worktree at `<projects root>/.wt/<project>/<task-id>` — a
+ * sibling of whatever directory the project was handed as, never a path of
+ * this module's own choosing, so a project outside this clone keeps its
+ * worktrees outside it too (see taskWorktreeDir)
+ * on branch smith/<epic>/<task-id>, cut from the CURRENT head of
+ * smith/<epic>/integration (creating the integration branch from the default
+ * branch first if it doesn't exist yet).
+ */
+export function createTaskWorktree(projectDir, epic, taskId) {
+    if (taskId === RESERVED_TASK_ID) {
+        throw new WorktreeError('worktree.reserved-task-id', `Task id "${RESERVED_TASK_ID}" is reserved for the integration branch itself.`, { taskId });
+    }
+    const integrationBranch = ensureIntegrationBranch(projectDir, epic);
+    const branch = taskBranchName(epic, taskId);
+    const worktreeDir = taskWorktreeDir(projectDir, epic, taskId);
+    git(projectDir, ['worktree', 'add', '-b', branch, worktreeDir, integrationBranch]);
+    return { worktreeDir, branch, epic, taskId };
+}
+/** Remove a task's worktree and its local branch after it has merged. */
+export function removeTaskWorktree(projectDir, epic, taskId) {
+    const worktreeDir = taskWorktreeDir(projectDir, epic, taskId);
+    const branch = taskBranchName(epic, taskId);
+    try {
+        git(projectDir, ['worktree', 'remove', worktreeDir]);
+    }
+    catch (err) {
+        throw new WorktreeError('worktree.remove-failed', `Failed to remove worktree at ${worktreeDir}: ${err instanceof Error ? err.message : String(err)}`, { worktreeDir });
+    }
+    try {
+        git(projectDir, ['branch', '-d', branch]);
+    }
+    catch (err) {
+        throw new WorktreeError('worktree.branch-delete-failed', `Failed to delete branch ${branch} (not fully merged?): ${err instanceof Error ? err.message : String(err)}`, { branch });
+    }
+}
+function parseWorktreePorcelain(output) {
+    const entries = [];
+    let current = null;
+    for (const line of output.split('\n')) {
+        if (line.startsWith('worktree ')) {
+            if (current?.worktree)
+                entries.push({ worktree: current.worktree, branch: current.branch ?? null });
+            current = { worktree: line.slice('worktree '.length), branch: null };
+        }
+        else if (line.startsWith('branch ') && current) {
+            current.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+        }
+        else if (line === '' && current?.worktree) {
+            entries.push({ worktree: current.worktree, branch: current.branch ?? null });
+            current = null;
+        }
+    }
+    if (current?.worktree)
+        entries.push({ worktree: current.worktree, branch: current.branch ?? null });
+    return entries;
+}
+/**
+ * List task worktrees whose branch is fully merged into smith/<epic>/integration.
+ * Reports only — never deletes.
+ */
+export function listStale(projectDir, epic) {
+    const integrationBranch = integrationBranchName(epic);
+    const prefix = `smith/${epic}/`;
+    const porcelain = git(projectDir, ['worktree', 'list', '--porcelain']);
+    const entries = parseWorktreePorcelain(porcelain);
+    const stale = [];
+    for (const entry of entries) {
+        if (!entry.branch?.startsWith(prefix))
+            continue;
+        const taskId = entry.branch.slice(prefix.length);
+        if (taskId === RESERVED_TASK_ID)
+            continue;
+        try {
+            git(projectDir, ['merge-base', '--is-ancestor', entry.branch, integrationBranch]);
+            stale.push({ worktreeDir: entry.worktree, branch: entry.branch, taskId });
+        }
+        catch {
+            // not an ancestor -> not merged yet, not stale
+        }
+    }
+    return stale;
+}

package/factory/orchestrator/drizzle/0000_broken_rockslide.sql

@@ -0,0 +1,183 @@
+CREATE TABLE `agents` (
+	`id` text PRIMARY KEY NOT NULL,
+	`session_id` text NOT NULL,
+	`task_id` text,
+	`agent_id` text,
+	`agent_role` text NOT NULL,
+	`provider` text NOT NULL,
+	`model_tier` text NOT NULL,
+	`dispatched_at` text NOT NULL,
+	`terminal_event_id` text,
+	`terminal_at` text,
+	`terminal_type` text,
+	`status` text NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `agents_session_idx` ON `agents` (`session_id`);--> statement-breakpoint
+CREATE INDEX `agents_status_idx` ON `agents` (`status`);--> statement-breakpoint
+CREATE INDEX `agents_role_idx` ON `agents` (`agent_role`);--> statement-breakpoint
+CREATE TABLE `artifacts` (
+	`id` text PRIMARY KEY NOT NULL,
+	`session_id` text NOT NULL,
+	`task_id` text NOT NULL,
+	`event_id` text NOT NULL,
+	`ts` text NOT NULL,
+	`type` text NOT NULL,
+	`path` text NOT NULL,
+	`description` text
+);
+--> statement-breakpoint
+CREATE INDEX `artifacts_session_idx` ON `artifacts` (`session_id`);--> statement-breakpoint
+CREATE INDEX `artifacts_task_idx` ON `artifacts` (`task_id`);--> statement-breakpoint
+CREATE TABLE `dispatches` (
+	`event_id` text PRIMARY KEY NOT NULL,
+	`session_id` text NOT NULL,
+	`ts` text NOT NULL,
+	`task_id` text,
+	`agent_id` text,
+	`agent_role` text NOT NULL,
+	`provider` text NOT NULL,
+	`model_tier` text NOT NULL,
+	`spec_ref` text,
+	`reason` text,
+	`parent_prompt_id` text,
+	`causal_parent` text
+);
+--> statement-breakpoint
+CREATE INDEX `dispatches_session_idx` ON `dispatches` (`session_id`);--> statement-breakpoint
+CREATE INDEX `dispatches_task_idx` ON `dispatches` (`task_id`);--> statement-breakpoint
+CREATE INDEX `dispatches_role_idx` ON `dispatches` (`agent_role`);--> statement-breakpoint
+CREATE INDEX `dispatches_provider_idx` ON `dispatches` (`provider`);--> statement-breakpoint
+CREATE INDEX `dispatches_model_tier_idx` ON `dispatches` (`model_tier`);--> statement-breakpoint
+CREATE TABLE `edges` (
+	`event_id` text PRIMARY KEY NOT NULL,
+	`session_id` text NOT NULL,
+	`ts` text NOT NULL,
+	`task_id` text NOT NULL,
+	`depends_on` text NOT NULL,
+	`edge_type` text NOT NULL,
+	`edge_provenance` text NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `edges_session_idx` ON `edges` (`session_id`);--> statement-breakpoint
+CREATE INDEX `edges_task_idx` ON `edges` (`task_id`);--> statement-breakpoint
+CREATE TABLE `errors` (
+	`event_id` text PRIMARY KEY NOT NULL,
+	`session_id` text NOT NULL,
+	`ts` text NOT NULL,
+	`task_ref` text,
+	`agent_id` text,
+	`error_group` text NOT NULL,
+	`error_class` text NOT NULL,
+	`severity` text NOT NULL,
+	`detail` text
+);
+--> statement-breakpoint
+CREATE INDEX `errors_session_idx` ON `errors` (`session_id`);--> statement-breakpoint
+CREATE INDEX `errors_group_idx` ON `errors` (`error_group`);--> statement-breakpoint
+CREATE INDEX `errors_severity_idx` ON `errors` (`severity`);--> statement-breakpoint
+CREATE INDEX `errors_ts_idx` ON `errors` (`ts`);--> statement-breakpoint
+CREATE TABLE `events_raw` (
+	`event_id` text PRIMARY KEY NOT NULL,
+	`session_id` text NOT NULL,
+	`ts` text NOT NULL,
+	`event_type` text NOT NULL,
+	`task_id` text,
+	`agent_id` text,
+	`plan_version` integer NOT NULL,
+	`causal_parent` text,
+	`payload` text NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `events_raw_session_idx` ON `events_raw` (`session_id`);--> statement-breakpoint
+CREATE INDEX `events_raw_task_idx` ON `events_raw` (`task_id`);--> statement-breakpoint
+CREATE INDEX `events_raw_type_idx` ON `events_raw` (`event_type`);--> statement-breakpoint
+CREATE INDEX `events_raw_ts_idx` ON `events_raw` (`ts`);--> statement-breakpoint
+CREATE TABLE `findings` (
+	`finding_id` text PRIMARY KEY NOT NULL,
+	`session_id` text NOT NULL,
+	`task_id` text NOT NULL,
+	`epic_id` text,
+	`fingerprint` text NOT NULL,
+	`finding_category` text NOT NULL,
+	`severity` text NOT NULL,
+	`finding_status` text NOT NULL,
+	`summary` text NOT NULL,
+	`found_by` text NOT NULL,
+	`found_by_provider` text,
+	`verified_by` text,
+	`verified_by_provider` text,
+	`same_mistake_of_lesson_id` text,
+	`waiver_id` text,
+	`raised_at` text NOT NULL,
+	`updated_at` text NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `findings_session_idx` ON `findings` (`session_id`);--> statement-breakpoint
+CREATE INDEX `findings_task_idx` ON `findings` (`task_id`);--> statement-breakpoint
+CREATE INDEX `findings_status_idx` ON `findings` (`finding_status`);--> statement-breakpoint
+CREATE INDEX `findings_severity_idx` ON `findings` (`severity`);--> statement-breakpoint
+CREATE INDEX `findings_fingerprint_idx` ON `findings` (`fingerprint`);--> statement-breakpoint
+CREATE TABLE `lessons` (
+	`lesson_id` text PRIMARY KEY NOT NULL,
+	`session_id` text NOT NULL,
+	`lesson_type` text NOT NULL,
+	`lesson_level` text NOT NULL,
+	`lesson_status` text NOT NULL,
+	`lesson_scope` text NOT NULL,
+	`statement` text NOT NULL,
+	`valid_from` text NOT NULL,
+	`superseded_by` text,
+	`invalidated_by_event_id` text,
+	`provenance_event_ids` text,
+	`evidence` text,
+	`times_prevented` integer DEFAULT 0 NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `lessons_session_idx` ON `lessons` (`session_id`);--> statement-breakpoint
+CREATE INDEX `lessons_status_idx` ON `lessons` (`lesson_status`);--> statement-breakpoint
+CREATE TABLE `prompts` (
+	`event_id` text PRIMARY KEY NOT NULL,
+	`session_id` text NOT NULL,
+	`ts` text NOT NULL,
+	`prompt` text NOT NULL,
+	`causal_parent` text
+);
+--> statement-breakpoint
+CREATE INDEX `prompts_session_idx` ON `prompts` (`session_id`);--> statement-breakpoint
+CREATE TABLE `sessions` (
+	`session_id` text PRIMARY KEY NOT NULL,
+	`started_at` text NOT NULL,
+	`last_event_at` text NOT NULL,
+	`event_count` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `tasks` (
+	`task_id` text PRIMARY KEY NOT NULL,
+	`session_id` text NOT NULL,
+	`epic_id` text,
+	`case_tag` text,
+	`origin` text,
+	`task_status` text NOT NULL,
+	`plan_version` integer,
+	`objective` text,
+	`claims` text,
+	`branch` text,
+	`created_at` text NOT NULL,
+	`updated_at` text NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `tasks_session_idx` ON `tasks` (`session_id`);--> statement-breakpoint
+CREATE INDEX `tasks_epic_idx` ON `tasks` (`epic_id`);--> statement-breakpoint
+CREATE INDEX `tasks_status_idx` ON `tasks` (`task_status`);--> statement-breakpoint
+CREATE TABLE `waivers` (
+	`event_id` text PRIMARY KEY NOT NULL,
+	`session_id` text NOT NULL,
+	`ts` text NOT NULL,
+	`fingerprint` text NOT NULL,
+	`decision` text NOT NULL,
+	`operator_note` text
+);
+--> statement-breakpoint
+CREATE INDEX `waivers_session_idx` ON `waivers` (`session_id`);--> statement-breakpoint
+CREATE INDEX `waivers_fingerprint_idx` ON `waivers` (`fingerprint`);

package/factory/orchestrator/drizzle/0001_luxuriant_zaladane.sql

@@ -0,0 +1 @@
+ALTER TABLE `tasks` ADD `budget_tokens` integer;

package/factory/orchestrator/drizzle/0002_yellow_wild_pack.sql

@@ -0,0 +1,8 @@
+CREATE TABLE `milestones` (
+	`milestone_id` text PRIMARY KEY NOT NULL,
+	`name` text NOT NULL,
+	`status` text NOT NULL,
+	`sequence` integer NOT NULL,
+	`goal` text,
+	`epic_ids` text NOT NULL
+);

package/factory/orchestrator/drizzle/0003_damp_riptide.sql

@@ -0,0 +1,12 @@
+ALTER TABLE `dispatches` ADD `project` text;--> statement-breakpoint
+CREATE INDEX `dispatches_project_idx` ON `dispatches` (`project`);--> statement-breakpoint
+ALTER TABLE `errors` ADD `project` text;--> statement-breakpoint
+CREATE INDEX `errors_project_idx` ON `errors` (`project`);--> statement-breakpoint
+ALTER TABLE `events_raw` ADD `project` text;--> statement-breakpoint
+CREATE INDEX `events_raw_project_idx` ON `events_raw` (`project`);--> statement-breakpoint
+ALTER TABLE `findings` ADD `project` text;--> statement-breakpoint
+CREATE INDEX `findings_project_idx` ON `findings` (`project`);--> statement-breakpoint
+ALTER TABLE `milestones` ADD `project` text DEFAULT 'black-smith' NOT NULL;--> statement-breakpoint
+CREATE INDEX `milestones_project_idx` ON `milestones` (`project`);--> statement-breakpoint
+ALTER TABLE `tasks` ADD `project` text;--> statement-breakpoint
+CREATE INDEX `tasks_project_idx` ON `tasks` (`project`);

package/factory/orchestrator/drizzle/0004_broad_lady_vermin.sql

@@ -0,0 +1 @@
+ALTER TABLE `events_raw` ADD `actor` text;

package/factory/orchestrator/drizzle/0005_romantic_jocasta.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `lessons` ADD `finding_category` text;--> statement-breakpoint
+ALTER TABLE `lessons` ADD `claim_path` text;

package/factory/orchestrator/drizzle/0006_bent_madelyne_pryor.sql

@@ -0,0 +1,16 @@
+CREATE TABLE `epics` (
+	`epic_id` text PRIMARY KEY NOT NULL,
+	`session_id` text NOT NULL,
+	`epic_status` text NOT NULL,
+	`closed_by` text NOT NULL,
+	`machine_verdict` text,
+	`machine_reason` text,
+	`override_rationale` text,
+	`blockers` text,
+	`closed_at` text NOT NULL,
+	`event_id` text NOT NULL,
+	`project` text
+);
+--> statement-breakpoint
+CREATE INDEX `epics_session_idx` ON `epics` (`session_id`);--> statement-breakpoint
+CREATE INDEX `epics_project_idx` ON `epics` (`project`);

package/factory/orchestrator/drizzle/0007_overjoyed_goliath.sql

@@ -0,0 +1 @@
+ALTER TABLE `agents` ADD `round` integer DEFAULT 1 NOT NULL;

package/factory/orchestrator/drizzle/0008_smart_iron_patriot.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `lessons` ADD `agent_role` text;--> statement-breakpoint
+ALTER TABLE `lessons` ADD `case_type` text;

package/factory/orchestrator/drizzle/0009_agents_epic_id.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `agents` ADD `epic_id` text;--> statement-breakpoint
+CREATE INDEX `agents_epic_idx` ON `agents` (`epic_id`);

package/factory/orchestrator/drizzle/0010_milestone_kind.sql

@@ -0,0 +1 @@
+ALTER TABLE `milestones` ADD `kind` text DEFAULT 'factory' NOT NULL;

package/factory/orchestrator/drizzle/meta/_journal.json

@@ -0,0 +1,83 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1785818885974,
+      "tag": "0000_broken_rockslide",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1785819387767,
+      "tag": "0001_luxuriant_zaladane",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "6",
+      "when": 1785823535112,
+      "tag": "0002_yellow_wild_pack",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "6",
+      "when": 1785831313729,
+      "tag": "0003_damp_riptide",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "6",
+      "when": 1785831788547,
+      "tag": "0004_broad_lady_vermin",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "6",
+      "when": 1785851922349,
+      "tag": "0005_romantic_jocasta",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "6",
+      "when": 1786081446525,
+      "tag": "0006_bent_madelyne_pryor",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "6",
+      "when": 1786132918663,
+      "tag": "0007_overjoyed_goliath",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "6",
+      "when": 1786939800891,
+      "tag": "0008_smart_iron_patriot",
+      "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "6",
+      "when": 1787382509200,
+      "tag": "0009_agents_epic_id",
+      "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "6",
+      "when": 1788429177107,
+      "tag": "0010_milestone_kind",
+      "breakpoints": true
+    }
+  ]
+}