@juzser/blacksmith 0.1.0

package/factory/specs/schema/mcp-manifest.schema.json

@@ -0,0 +1,230 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://black-smith.dev/schema/mcp-manifest.schema.json",
+  "$comment": "Shape contract for a project's mcp.manifest.json. The verdict that gates epic close comes from checkManifest() in factory/orchestrator/src/mcp.ts, which reports stable rule ids (MCP-P1, MCP-T4, ...) from the numbered baseline in docs/standards/mcp.md; this schema is the shape half of the same contract and its descriptions name the rule each field serves. Rules that are not decidable from a declaration (MCP-P3 session independence, MCP-S1 output redaction, MCP-X5 state-handle binding, MCP-X6 SSRF blocks) are enforced in code, not here.",
+  "title": "MCP Manifest",
+  "description": "The single declaration of what a project's MCP surface exposes: its identity, its wire revision, its transport, and every tool with its mutation class, annotations, and operator sign-off. This file is the one place an operator reads to know what an agent can do with this project.",
+  "type": "object",
+  "required": ["name", "version", "protocolRevision", "transport", "tools"],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "MCP-P2. Server identity as reported in the initialize result; conventionally the project name."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$",
+      "description": "MCP-P2. Semver. A client caches a tool surface against this, so bump it when the surface changes."
+    },
+    "protocolRevision": {
+      "type": "string",
+      "const": "2025-11-25",
+      "description": "MCP-P1. The pinned wire revision — what the Tier-1 TypeScript SDK actually negotiates, not the newest revision on paper. Moves to 2026-07-28 when the SDK ships it; see docs/standards/mcp.md 'Forward compatibility'."
+    },
+    "transport": {
+      "$ref": "#/$defs/transport"
+    },
+    "tools": {
+      "type": "array",
+      "description": "MCP-T5. Every tool the server registers, and nothing it does not. A server that can do more than this array admits makes the manifest a lie.",
+      "items": { "$ref": "#/$defs/tool" }
+    }
+  },
+  "$defs": {
+    "transport": {
+      "description": "MCP-X1. stdio is the default and opens no port; http is a deliberate opt-in that must carry its own preconditions.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["kind"],
+          "properties": {
+            "kind": { "const": "stdio" }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["kind", "access", "resourceServer"],
+          "properties": {
+            "kind": { "const": "http" },
+            "access": {
+              "type": "object",
+              "required": ["cloudflareAccess"],
+              "properties": {
+                "cloudflareAccess": {
+                  "const": true,
+                  "description": "MCP-X2 (mcp.md). Cloudflare Access in front: nothing is exposed beyond localhost without something authenticating for it."
+                }
+              }
+            },
+            "resourceServer": {
+              "type": "object",
+              "description": "MCP-X3/X4. The server is an OAuth 2.0 protected resource, and says so precisely enough to be checkable.",
+              "required": [
+                "canonicalUri",
+                "authorizationServers",
+                "resourceIndicators",
+                "tokenPassthrough"
+              ],
+              "properties": {
+                "canonicalUri": {
+                  "type": "string",
+                  "pattern": "^https://",
+                  "description": "MCP-X3. The canonical resource URI. This is the token audience — every accepted token must name it."
+                },
+                "authorizationServers": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": { "type": "string", "pattern": "^https://" },
+                  "description": "MCP-X3. Issuers this resource trusts. Validate the returned `iss` against these (RFC 9207) to close the mix-up attack."
+                },
+                "resourceIndicators": {
+                  "const": true,
+                  "description": "MCP-X3. RFC 8707 resource indicators are mandatory: they are what binds an issued token to this server rather than to whoever asks next."
+                },
+                "tokenPassthrough": {
+                  "const": false,
+                  "description": "MCP-X4. Never allowed. The server MUST NOT accept any token that was not explicitly issued for it."
+                },
+                "scopes": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Least privilege. Wildcards ('*', 'all', 'full-access') defeat the point of asking."
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "tool": {
+      "type": "object",
+      "required": ["name", "title", "description", "mutation", "annotations"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]{2,63}$",
+          "description": "MCP-T5. snake_case, unique within the manifest. This is what an agent types."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-facing label, shown in consent prompts."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "What the tool does, written for the agent deciding whether to call it."
+        },
+        "mutation": {
+          "enum": ["read-only", "write", "destructive", "outbound"],
+          "description": "MCP-T2. What this tool actually does to the world. read-only is the default and the only class that needs no sign-off. The implementation passes this same class to requireDeclaredTool(), so a tool that quietly starts writing fails to boot instead of shipping under its old declaration."
+        },
+        "annotations": {
+          "type": "object",
+          "description": "MCP-T1/T2/T3. The hints an agent reads to decide whether a call is safe. They must agree with `mutation` — a read-only tool with destructiveHint true is a contradiction, not a nuance.",
+          "required": [
+            "readOnlyHint",
+            "destructiveHint",
+            "idempotentHint",
+            "openWorldHint"
+          ],
+          "properties": {
+            "readOnlyHint": { "type": "boolean" },
+            "destructiveHint": { "type": "boolean" },
+            "idempotentHint": { "type": "boolean" },
+            "openWorldHint": {
+              "type": "boolean",
+              "description": "MCP-T3. True when the tool reaches something outside this project's own state. Every outbound tool sets it."
+            }
+          }
+        },
+        "approval": {
+          "type": "object",
+          "description": "MCP-T4. Operator sign-off, required for every tool that is not read-only. A person decided, at the mcp surface milestone, that an agent may do this unattended.",
+          "required": ["operator", "date", "milestone"],
+          "properties": {
+            "operator": { "type": "string", "minLength": 1 },
+            "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
+            "milestone": { "type": "string", "minLength": 1 }
+          }
+        }
+      },
+      "allOf": [
+        {
+          "$comment": "MCP-T1. read-only implies its own annotations.",
+          "if": {
+            "properties": { "mutation": { "const": "read-only" } },
+            "required": ["mutation"]
+          },
+          "then": {
+            "properties": {
+              "annotations": {
+                "properties": {
+                  "readOnlyHint": { "const": true },
+                  "destructiveHint": { "const": false },
+                  "openWorldHint": { "const": false }
+                }
+              }
+            }
+          }
+        },
+        {
+          "$comment": "MCP-T4. Anything that is not read-only carries a sign-off.",
+          "if": {
+            "properties": { "mutation": { "not": { "const": "read-only" } } },
+            "required": ["mutation"]
+          },
+          "then": { "required": ["approval"] }
+        },
+        {
+          "$comment": "MCP-T2. A mutating tool must not advertise itself as safe.",
+          "if": {
+            "properties": {
+              "mutation": { "enum": ["write", "destructive", "outbound"] }
+            },
+            "required": ["mutation"]
+          },
+          "then": {
+            "properties": {
+              "annotations": {
+                "properties": { "readOnlyHint": { "const": false } }
+              }
+            }
+          }
+        },
+        {
+          "$comment": "MCP-T2. destructive means destructive.",
+          "if": {
+            "properties": { "mutation": { "const": "destructive" } },
+            "required": ["mutation"]
+          },
+          "then": {
+            "properties": {
+              "annotations": {
+                "properties": { "destructiveHint": { "const": true } }
+              }
+            }
+          }
+        },
+        {
+          "$comment": "MCP-T3. outbound reaches beyond this project.",
+          "if": {
+            "properties": { "mutation": { "const": "outbound" } },
+            "required": ["mutation"]
+          },
+          "then": {
+            "properties": {
+              "annotations": {
+                "properties": { "openWorldHint": { "const": true } }
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/factory/specs/schema/result.schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://black-smith.dev/schema/result.schema.json",
+  "$comment": "Taxonomy-valued fields carry an x-taxonomy annotation naming the dimension in factory/policies/taxonomy.yml. The runtime validates those values against that file at write time; enums are never inlined here to avoid drift between the schema and the taxonomy (architecture §8).",
+  "title": "Task Result",
+  "description": "Structured return from a worker run. Workers return schema-validated results, never transcripts (architecture §15.4); the final message is data, not prose.",
+  "type": "object",
+  "required": [
+    "task_id",
+    "run_status",
+    "structured_output",
+    "artifacts",
+    "token_usage",
+    "agent",
+    "provider",
+    "model_tier"
+  ],
+  "properties": {
+    "task_id": { "type": "string" },
+    "run_status": {
+      "type": "string",
+      "x-taxonomy": "run_status"
+    },
+    "structured_output": {
+      "type": "object",
+      "description": "Task-specific payload; shape is defined by the task spec's output_schema_ref, not by this envelope."
+    },
+    "artifacts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["type", "path"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "e.g. screenshot, diff, log, coverage-report."
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Under the task's artifact home, state/artifacts/<task_id>/ — relative to it by preference. JSON Schema cannot express \"inside this directory\", so the gate is the enforcer: it resolves each path in the home and blocks with reason 'artifacts-missing' if one is elsewhere or absent. The empty string is the one part the schema can catch, and it does (D-193): a worker that names no path gets a validation error at the envelope rather than a gate block one step later."
+          },
+          "description": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "token_usage": {
+      "type": "object",
+      "required": ["input_tokens", "output_tokens", "total_tokens"],
+      "properties": {
+        "input_tokens": { "type": "integer", "minimum": 0 },
+        "output_tokens": { "type": "integer", "minimum": 0 },
+        "total_tokens": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "agent": {
+      "type": "string",
+      "x-taxonomy": "agent"
+    },
+    "provider": {
+      "type": "string",
+      "x-taxonomy": "provider"
+    },
+    "model_tier": {
+      "type": "string",
+      "x-taxonomy": "model_tier"
+    },
+    "diff_lines_changed": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Excludes lockfiles/generated files, per the coder diff cap (agent-constraints.md)."
+    },
+    "notes": {
+      "type": "string",
+      "description": "Short structured note, e.g. reason for stopping at a budget cap."
+    }
+  },
+  "additionalProperties": false
+}

package/factory/specs/schema/spec-change-request.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://black-smith.dev/schema/spec-change-request.schema.json",
+  "$comment": "Taxonomy-valued fields carry an x-taxonomy annotation naming the dimension in factory/policies/taxonomy.yml. The runtime validates those values against that file at write time; enums are never inlined here to avoid drift between the schema and the taxonomy (architecture §8).",
+  "title": "Spec Change Request",
+  "description": "A worker's third exit, returned in structured_output alongside research_request and never emitted as an event — a worker that stops mid-flight cannot emit anything, so signalling through a returned field is the only shape that survives its own failure case (architecture §15). It says the criterion is wrong and what it should say instead. It is a proposal, not an amendment: nothing here moves a plan file, and only an operator's approval reaches `plan amend`.",
+  "type": "object",
+  "required": ["criterion_ref", "assumption", "evidence", "changes", "sites", "blocking"],
+  "properties": {
+    "criterion_ref": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Which acceptance criterion the worker read and found wrong. \"The plan is wrong\" has to say which clause — the same rule mintFindings enforces on spec-review evidence."
+    },
+    "assumption": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The assumption that criterion makes, stated as the worker understood it before it broke. This is what the operator is being asked to overturn, so it is recorded in the worker's words rather than paraphrased from the diff."
+    },
+    "evidence": {
+      "type": "string",
+      "minLength": 1,
+      "description": "What the worker found that contradicts the assumption — the file it read, the signature it hit, the test that cannot be written. A proposal without it is an opinion, and the operator is the one who would have to go and check."
+    },
+    "changes": {
+      "type": "object",
+      "description": "The proposed diff, in PlanChanges shape: {added?, supersede?, newEdges?}. Validated at proposal time by drafting the next version and running the plan's own validator over it, so a proposal that could never be applied is refused before it reaches an operator's queue rather than after."
+    },
+    "sites": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Every place the wrong assumption's shape occurs, not only where the worker hit it (D-123). The worker is better placed to enumerate these than the operator, which is the whole reason this field is asked for here rather than typed at approval."
+    },
+    "blocking": {
+      "type": "boolean",
+      "description": "Whether the worker can make any further progress without the amendment. Mirrors research_request.blocking. A blocking proposal left unreviewed is a stalled task, which is why the daemon reports it and a non-blocking one only waits."
+    },
+    "severity": {
+      "type": "string",
+      "x-taxonomy": "severity",
+      "description": "Optional. How badly the wrong criterion breaks the epic, if the worker has a view. Defaults at the dispatcher, never here: a schema default would make an absent field indistinguishable from a chosen one."
+    }
+  },
+  "additionalProperties": false
+}

package/factory/specs/schema/task-spec.schema.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://black-smith.dev/schema/task-spec.schema.json",
+  "$comment": "Taxonomy-valued fields carry an x-taxonomy annotation naming the dimension in factory/policies/taxonomy.yml. The runtime validates those values against that file at write time; enums are never inlined here to avoid drift between the schema and the taxonomy (architecture §8).",
+  "title": "Task Spec",
+  "description": "A dispatchable task contract: the unit the planner emits and a worker executes. Specs are contracts (architecture §1, §3) — no dispatch without objective, output schema, acceptance criteria, claims, and budget.",
+  "type": "object",
+  "required": [
+    "task_id",
+    "epic_id",
+    "plan_version",
+    "objective",
+    "output_schema_ref",
+    "acceptance_criteria",
+    "claims",
+    "budget",
+    "contract",
+    "case",
+    "origin",
+    "task_status"
+  ],
+  "properties": {
+    "task_id": {
+      "type": "string",
+      "description": "Stable identifier, e.g. epic-7/task-142."
+    },
+    "epic_id": {
+      "type": "string"
+    },
+    "plan_version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Immutable plan version this task was cut under (architecture §12); never mutated in place."
+    },
+    "objective": {
+      "type": "string",
+      "minLength": 1,
+      "description": "One-paragraph statement of what the task must accomplish."
+    },
+    "output_schema_ref": {
+      "type": "string",
+      "description": "Path or $id of the JSON Schema the task's result.structured_output must validate against."
+    },
+    "acceptance_criteria": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "claims": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "description": "File globs this task may touch, computed from static analysis over the target repo (architecture §5). Out-of-claim edits fail the gate."
+    },
+    "budget": {
+      "type": "object",
+      "description": "Declared caps for this task. Only fields something can mechanically read belong here — plan validation rejects the rest (src/budgets.ts TASK_BUDGET_FIELD_READERS).",
+      "required": ["tokens", "diff_lines"],
+      "properties": {
+        "tokens": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Compared at the gate against the result's token_usage.total_tokens."
+        },
+        "diff_lines": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Compared at the gate against the measured git diff, excluding lockfiles and generated files."
+        },
+        "max_turns": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Still schema-valid so plans written before 2026-08-08 load, but plan validation now rejects it: no dispatch harness can enforce a turn limit (agent-interviews.md M-4). The number belongs in the dispatch prompt, where it is a request."
+        }
+      },
+      "additionalProperties": false
+    },
+    "contract": {
+      "type": "object",
+      "description": "Explicit clauses the worker must satisfy. Nonfunctional/security clauses are always spelled out here — implicit clauses get dropped (error.spec.missing-nonfunctional).",
+      "required": ["functional_clauses", "nonfunctional_clauses"],
+      "properties": {
+        "functional_clauses": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        },
+        "nonfunctional_clauses": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Explicit security/validation/authz/performance/a11y clauses, even when they seem implied by the objective."
+        },
+        "tool_allowlist": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "case": {
+      "type": "string",
+      "x-taxonomy": "case"
+    },
+    "origin": {
+      "type": "string",
+      "x-taxonomy": "origin"
+    },
+    "task_status": {
+      "type": "string",
+      "x-taxonomy": "task_status"
+    },
+    "agent_role": {
+      "type": "string",
+      "x-taxonomy": "agent",
+      "description": "Role of the agent this task is scoped to be dispatched to."
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Set only for origin: inferred tasks (architecture §12); >=0.8 auto-schedules."
+    },
+    "dependency_edge_ids": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "IDs of edge-recorded events this task depends on (architecture §7)."
+    },
+    "project": {
+      "type": "string",
+      "description": "Optional plain-string project identifier (Phase 6b, architecture §8) — NOT a closed taxonomy.yml vocabulary value (projects open/close far more often than any §8 dimension). Absent tasks default to 'black-smith' in the projection layer."
+    }
+  },
+  "additionalProperties": false
+}

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@juzser/blacksmith",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Autonomous agent factory — loop runner and worktree engine.",
+  "keywords": [
+    "agent",
+    "agents",
+    "ai",
+    "autonomous",
+    "claude-code",
+    "code-review",
+    "git-worktree",
+    "llm",
+    "multi-agent",
+    "orchestration"
+  ],
+  "homepage": "https://github.com/juzser/blacksmith#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juzser/blacksmith.git"
+  },
+  "bugs": {
+    "url": "https://github.com/juzser/blacksmith/issues"
+  },
+  "author": "juzser (https://github.com/juzser)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@9.3.0",
+  "bin": {
+    "smith": "factory/orchestrator/dist/cli.js"
+  },
+  "files": [
+    "factory/orchestrator/dist",
+    "!factory/orchestrator/dist/**/*.d.ts",
+    "factory/orchestrator/drizzle",
+    "!factory/orchestrator/drizzle/meta/*_snapshot.json",
+    "factory/policies",
+    "factory/specs/schema",
+    "factory/scaffold",
+    ".claude/agents"
+  ],
+  "scripts": {
+    "prepare": "pnpm run build",
+    "check": "bash scripts/check.sh",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc -p tsconfig.test.json",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "build:server": "pnpm build && tsc -p ui/server/tsconfig.json",
+    "typecheck:server": "tsc -p ui/server/tsconfig.test.json",
+    "test:server": "pnpm build:server && vitest run --config ui/server/vitest.config.ts",
+    "test:server:coverage": "pnpm build:server && vitest run --config ui/server/vitest.config.ts --coverage",
+    "build:ui": "vite build --config ui/vite.config.ts",
+    "dev:ui": "vite --config ui/vite.config.ts",
+    "typecheck:ui": "tsc -p ui/tsconfig.json",
+    "typecheck:ui:test": "tsc -p ui/tsconfig.test.json",
+    "test:ui": "vitest run --config ui/vitest.config.ts",
+    "test:ui:coverage": "vitest run --config ui/vitest.config.ts --coverage",
+    "test:e2e": "pnpm build:server && pnpm build:ui && playwright test --config ui/playwright.config.ts"
+  },
+  "dependencies": {
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "better-sqlite3": "13.0.3",
+    "drizzle-orm": "0.45.2",
+    "picomatch": "4.0.7",
+    "yaml": "2.9.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.12",
+    "@hono/node-server": "2.1.1",
+    "@playwright/test": "1.63.0",
+    "@tailwindcss/vite": "4.3.3",
+    "@types/better-sqlite3": "9.6.0",
+    "@types/node": "26.4.1",
+    "@vitejs/plugin-vue": "6.0.8",
+    "@vitest/coverage-v8": "5.0.0",
+    "@vue-flow/core": "1.48.2",
+    "drizzle-kit": "0.31.10",
+    "hono": "4.13.7",
+    "tailwindcss": "4.3.3",
+    "typescript": "7.0.2",
+    "vite": "8.2.2",
+    "vitest": "5.0.0",
+    "vue": "3.5.42",
+    "vue-router": "5.3.1"
+  }
+}