ghostrail 0.0.0 → 0.1.0

package/dist/triage/engine.js

@@ -0,0 +1,122 @@
+import { stageArtifacts } from "../global/stage.js";
+import { branchName } from "../loop/branch.js";
+import { mapWithConcurrency } from "../loop/concurrency.js";
+import { applyTriagePlan } from "./apply.js";
+import { parseTriagePlan } from "./plan.js";
+/** Path, relative to the workspace root, where the triage agent writes its plan. */
+export const TRIAGE_PLAN_PATH = ".ghostrail/triage.json";
+const BRANCH_PREFIX = "triage";
+const nullLogger = { info: () => { }, warn: () => { } };
+async function readWorkspaceFile(backend, workspace, path) {
+    const result = await backend.exec(workspace, ["cat", path]);
+    return result.exitCode === 0 ? result.stdout : undefined;
+}
+async function ignoreErrors(action) {
+    try {
+        await action();
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * Run one triage tick: discover issues in the triage queue and, for each (up to
+ * the guardrails), claim it, provision a workspace for repo context, run the
+ * triage agent (which writes a decomposition plan), and apply that plan through
+ * the source. Like the run loop it holds a single global lock and never touches
+ * code or PRs. Requires `config.triage` to be set.
+ */
+export async function triageTick(deps, config) {
+    const logger = deps.logger ?? nullLogger;
+    if (config.triage === undefined) {
+        throw new Error("triage requires a [triage] config section");
+    }
+    const triage = config.triage;
+    const acquired = await deps.lock.acquire();
+    if (!acquired) {
+        logger.warn("another tick holds the lock; skipping");
+        return { lockAcquired: false, results: [] };
+    }
+    try {
+        const eligible = await deps.source.listEligible();
+        const items = eligible.slice(0, config.guardrails.maxItemsPerRun);
+        logger.info(`triage: discovered ${eligible.length} item(s), taking ${items.length}`);
+        const results = await mapWithConcurrency(items, config.guardrails.concurrency, (item) => triageItem(deps, config, triage.prompt, item, logger));
+        return { lockAcquired: true, results };
+    }
+    finally {
+        await deps.lock.release();
+    }
+}
+async function triageItem(deps, config, prompt, item, logger) {
+    let workspace;
+    try {
+        const claimed = await deps.source.claim(item);
+        if (!claimed) {
+            logger.info(`${item.id}: claim lost, skipping`);
+            return { itemId: item.id, state: "noop" };
+        }
+        const source = config.factory.source;
+        workspace = await deps.backend.provision({
+            repoPath: source ?? deps.repoPath,
+            baseBranch: config.factory.baseBranch,
+            branch: branchName(BRANCH_PREFIX, item.id, item.title),
+            ...(source === undefined ? {} : { clone: true }),
+            ...(config.backend.image === undefined ? {} : { image: config.backend.image }),
+        });
+        if (deps.globalStore !== undefined && config.artifacts.length > 0) {
+            await stageArtifacts(deps.backend, workspace, deps.globalStore, config.artifacts, logger);
+        }
+        const agentConfig = {
+            kind: config.agent.kind,
+            prompt,
+            allowedTools: config.agent.allowedTools,
+        };
+        const outcome = await deps.agent.run({
+            backend: deps.backend,
+            workspace,
+            item,
+            agent: agentConfig,
+            guardrails: config.guardrails,
+        });
+        return await route(deps, item, workspace, outcome, logger);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.warn(`${item.id}: triage errored, resetting: ${message}`);
+        await ignoreErrors(() => deps.source.reset(item));
+        return { itemId: item.id, state: "failed", error: message };
+    }
+    finally {
+        if (workspace !== undefined) {
+            await ignoreErrors(() => deps.backend.teardown(workspace));
+        }
+    }
+}
+async function route(deps, item, workspace, outcome, logger) {
+    if (outcome.status === "blocked") {
+        logger.info(`${item.id}: triage blocked, handing back to a human`);
+        await deps.source.comment(item, outcome.questions ?? "Triage needs a decision.");
+        await deps.source.reassignToHuman(item);
+        return { itemId: item.id, state: "noop" };
+    }
+    if (outcome.status === "failed") {
+        await deps.source.comment(item, `Triage failed: ${outcome.error ?? "unknown error"}`);
+        await deps.source.reset(item);
+        return { itemId: item.id, state: "failed", error: outcome.error ?? "unknown error" };
+    }
+    const raw = await readWorkspaceFile(deps.backend, workspace, TRIAGE_PLAN_PATH);
+    if (raw === undefined || raw.trim().length === 0) {
+        await deps.source.comment(item, "Triage produced no plan.");
+        await deps.source.reset(item);
+        return { itemId: item.id, state: "failed", error: "no triage plan written" };
+    }
+    const plan = parseTriagePlan(raw);
+    if (plan.status === "invalid") {
+        await deps.source.comment(item, `Triage plan was invalid: ${plan.error}`);
+        await deps.source.reset(item);
+        return { itemId: item.id, state: "failed", error: plan.error };
+    }
+    return applyTriagePlan(deps.source, item, plan, logger);
+}
+//# sourceMappingURL=engine.js.map

package/dist/triage/engine.js.map

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

package/dist/triage/index.d.ts

@@ -0,0 +1,4 @@
+export { type TriageResult, applyTriagePlan } from "./apply.js";
+export { type TriageDeps, TRIAGE_PLAN_PATH, type TriageTickResult, triageTick } from "./engine.js";
+export { type ParsedPlan, parseTriagePlan, type SubIssuePlan, type TriagePlan } from "./plan.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/triage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/triage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,KAAK,UAAU,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACnG,OAAO,EAAE,KAAK,UAAU,EAAE,eAAe,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC"}

package/dist/triage/index.js

@@ -0,0 +1,4 @@
+export { applyTriagePlan } from "./apply.js";
+export { TRIAGE_PLAN_PATH, triageTick } from "./engine.js";
+export { parseTriagePlan } from "./plan.js";
+//# sourceMappingURL=index.js.map

package/dist/triage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/triage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,eAAe,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAmB,gBAAgB,EAAyB,UAAU,EAAE,MAAM,aAAa,CAAC;AACnG,OAAO,EAAmB,eAAe,EAAsC,MAAM,WAAW,CAAC"}

package/dist/triage/plan.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The triage agent's output contract. It writes a JSON plan to a file in the
+ * workspace; ghostrail parses and validates it here, then applies it through the
+ * {@link TriageSource}. The agent never mutates the tracker directly.
+ */
+/** One proposed sub-issue in a split plan. */
+export interface SubIssuePlan {
+    title: string;
+    description?: string;
+    /**
+     * Indices (into the same `subIssues` array) of earlier sub-issues that must be
+     * done first. Each index must be a non-negative integer strictly less than
+     * this sub-issue's own index (dependencies point backward, so no cycles).
+     */
+    dependsOn?: number[];
+}
+/** A validated triage plan: either split the parent, or leave it as atomic. */
+export type TriagePlan = {
+    status: "split";
+    reason?: string;
+    subIssues: SubIssuePlan[];
+} | {
+    status: "noop";
+    reason?: string;
+};
+/** The result of parsing a plan: the plan, or a validation error. */
+export type ParsedPlan = TriagePlan | {
+    status: "invalid";
+    error: string;
+};
+/**
+ * Parse and validate the raw plan JSON the agent wrote. A `split` plan needs a
+ * non-empty `subIssues` array of `{ title, description?, dependsOn? }`; a `noop`
+ * plan needs nothing else. Anything malformed yields `{ status: "invalid" }`.
+ */
+export declare function parseTriagePlan(raw: string): ParsedPlan;
+//# sourceMappingURL=plan.d.ts.map

package/dist/triage/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/triage/plan.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,+EAA+E;AAC/E,MAAM,MAAM,UAAU,GAClB;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,YAAY,EAAE,CAAA;CAAE,GAC/D;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC,qEAAqE;AACrE,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAkC3E;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CA8BvD"}

package/dist/triage/plan.js

@@ -0,0 +1,75 @@
+/**
+ * The triage agent's output contract. It writes a JSON plan to a file in the
+ * workspace; ghostrail parses and validates it here, then applies it through the
+ * {@link TriageSource}. The agent never mutates the tracker directly.
+ */
+function invalid(error) {
+    return { status: "invalid", error };
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Validate one sub-issue at position `index`; return its normalized form or an error message. */
+function parseSubIssue(raw, index) {
+    if (!isRecord(raw))
+        return `subIssues[${index}] must be an object`;
+    const { title, description, dependsOn } = raw;
+    if (typeof title !== "string" || title.trim().length === 0) {
+        return `subIssues[${index}].title must be a non-empty string`;
+    }
+    const out = { title };
+    if (description !== undefined) {
+        if (typeof description !== "string")
+            return `subIssues[${index}].description must be a string`;
+        out.description = description;
+    }
+    if (dependsOn !== undefined) {
+        if (!Array.isArray(dependsOn))
+            return `subIssues[${index}].dependsOn must be an array`;
+        for (const dep of dependsOn) {
+            if (!Number.isInteger(dep) || dep < 0 || dep >= index) {
+                return `subIssues[${index}].dependsOn must be earlier indices (0..${index - 1})`;
+            }
+        }
+        out.dependsOn = dependsOn;
+    }
+    return out;
+}
+/**
+ * Parse and validate the raw plan JSON the agent wrote. A `split` plan needs a
+ * non-empty `subIssues` array of `{ title, description?, dependsOn? }`; a `noop`
+ * plan needs nothing else. Anything malformed yields `{ status: "invalid" }`.
+ */
+export function parseTriagePlan(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (error) {
+        return invalid(`not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRecord(value))
+        return invalid("plan must be a JSON object");
+    const { status, reason } = value;
+    if (reason !== undefined && typeof reason !== "string")
+        return invalid("reason must be a string");
+    const reasonField = reason === undefined ? {} : { reason: reason };
+    if (status === "noop")
+        return { status: "noop", ...reasonField };
+    if (status === "split") {
+        const { subIssues } = value;
+        if (!Array.isArray(subIssues) || subIssues.length === 0) {
+            return invalid('a "split" plan needs a non-empty subIssues array');
+        }
+        const parsed = [];
+        for (let i = 0; i < subIssues.length; i++) {
+            const result = parseSubIssue(subIssues[i], i);
+            if (typeof result === "string")
+                return invalid(result);
+            parsed.push(result);
+        }
+        return { status: "split", subIssues: parsed, ...reasonField };
+    }
+    return invalid('status must be "split" or "noop"');
+}
+//# sourceMappingURL=plan.js.map

package/dist/triage/plan.js.map

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

package/docker/factory.Dockerfile

@@ -0,0 +1,39 @@
+# Ghostrail factory toolchain image.
+#
+# The agent and the gate run INSIDE the backend workspace, so a container run
+# needs the full toolchain, not a bare shell:
+#   - node + pnpm  -> the gate (CI-mirror commands)
+#   - git + gh     -> commit, push, and open the PR
+#   - claude       -> the agent's inner loop (`claude -p`)
+#
+# Build it (see scripts/build-factory-image.sh) and point the config at it:
+#   [backend]
+#   kind  = "container"
+#   image = "ghostrail-factory:local"
+#
+# Credentials are never baked in; they are forwarded per run from the host
+# environment (ANTHROPIC_API_KEY, GH_TOKEN/GITHUB_TOKEN, LINEAR_API_KEY).
+FROM node:22-slim
+
+# git, the GitHub CLI, and TLS roots. gh comes from its own apt repository.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends ca-certificates curl git gnupg \
+ && install -m 0755 -d /etc/apt/keyrings \
+ && curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+      -o /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+ && chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+      > /etc/apt/sources.list.d/github-cli.list \
+ && apt-get update \
+ && apt-get install -y --no-install-recommends gh \
+ && rm -rf /var/lib/apt/lists/*
+
+# pnpm via corepack (bundled with Node), and the Claude Code CLI for the agent.
+RUN corepack enable \
+ && npm install -g @anthropic-ai/claude-code
+
+# Route GitHub https auth through gh's credential helper, so an in-container
+# `git push` authenticates from the forwarded GH_TOKEN (no token in any URL).
+RUN git config --system credential."https://github.com".helper "!gh auth git-credential"
+
+WORKDIR /work

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ghostrail",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Open source software factory for coding agents. Config-driven loops, pluggable isolation backends, human merge gate.",
   "keywords": [
     "ai-agents",
@@ -24,7 +24,7 @@
   "bin": {
     "ghostrail": "dist/bin.js"
   },
-  "files": ["dist", "templates", "LICENSE", "NOTICE", "README.md"],
+  "files": ["dist", "templates", "docker", "LICENSE", "NOTICE", "README.md"],
   "engines": {
     "node": ">=22"
   },
@@ -37,7 +37,8 @@
     "format": "biome format --write .",
     "test": "vitest run",
     "test:unit": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm lint && pnpm typecheck && pnpm test:unit && pnpm build"
   },
   "devDependencies": {
     "@biomejs/biome": "1.9.4",

package/templates/{fix-bugs-local → code-local}/README.md

@@ -1,12 +1,12 @@
-# fix-bugs-local
+# code-local
 
 A code factory that runs on your own hardware with zero infrastructure. It drains
 eligible tracker issues, fixes each in an isolated git worktree, gates the result
 against your CI, and opens a pull request. It never merges.
 
 ## Setup
-1. `ghostrail init fix-bugs-local` in your repo (or copy this folder in).
-2. Edit `ghostrail.toml`: set `source.project` to your Linear team key and the
+1. `ghostrail init code-local` in your repo (or copy this folder in).
+2. Edit `ghostrail.toml`: set `source.team` to your Linear team key and the
    `eligible` filter, and set `gate.commands` to your CI steps.
 3. Export `LINEAR_API_KEY` (a Linear personal API key) and make sure `gh` is
    authenticated for your repo.

package/templates/code-local/ghostrail.toml

@@ -0,0 +1,44 @@
+# code-local: a code factory on your own hardware, zero infrastructure.
+# Point it at a repo and a tracker queue; it resolves issues and opens PRs you merge.
+
+[factory]
+name = "code-local"
+base_branch = "main"
+
+[source]
+kind = "linear"                # linear | github-issues (Phase 2)
+team = "TJ"                 # your Linear team key
+eligible = { state = "Todo", label = "factory", assignee = "unassigned" }
+
+[agent]
+kind = "claude-code"
+prompt = "prompts/resolve-issue.md"
+# default allowed_tools = ["Read", "Edit", "Write", "Bash", "Grep", "Glob"]
+
+[backend]
+kind = "local-worktree"        # zero infrastructure; git worktree in place
+
+[gate]                         # the oracle: mirror your CI
+commands = [
+  "pnpm install --frozen-lockfile",
+  "pnpm lint",
+  "pnpm typecheck",
+  "pnpm test:unit",
+  "pnpm build",
+]
+
+[guardrails]
+max_items_per_run = 3
+budget_usd_per_item = 3
+timeout = "30m"
+
+[output]
+open_pr = true
+auto_merge = false             # a human owns every merge
+
+[respond]                      # `ghostrail respond` folds PR + tracker comments back in
+prompt = "prompts/respond.md"
+
+[triage]                       # `ghostrail triage` splits large issues into sub-issues
+prompt = "prompts/triage.md"
+eligible = { state = "Todo", label = "triage", assignee = "unassigned" }

package/templates/code-local/prompts/resolve-issue.md

@@ -0,0 +1,31 @@
+# Resolve an issue
+
+You are a coding agent working in an isolated checkout of this repository. Resolve
+the issue described below, whatever kind it is: a bug fix, a new feature, a
+refactor, or a docs change. You may only read and write files and run shell
+commands in this workspace. Do not use git: the factory owns commits, branches,
+and PRs.
+
+Match the surrounding code: its style, patterns, and test conventions.
+
+## The issue
+- ID: {{id}}
+- Title: {{title}}
+- Link: {{url}}
+
+## What to do
+1. Locate the relevant code and understand how it is structured.
+2. Make the smallest correct change that resolves the issue.
+3. Add or update tests (author them from the intent, not the implementation).
+4. Run the project's lint, typecheck, and unit-test commands and fix what you touched.
+
+## Reporting your result (required, do this last)
+Write a JSON file at `.ghostrail/result.json` with exactly one of:
+
+- `{"status":"done","summary":"<what you changed>","type":"<feat|fix|docs|refactor|chore|...>"}`
+- `{"status":"blocked","questions":"<a real product/design decision you need>"}`
+- `{"status":"failed","error":"<why>"}`
+- `{"status":"noop"}`
+
+`type` is the conventional-commit type for the change; it sets the commit and PR
+title. If you omit it, the factory's configured default is used.

package/templates/code-local/prompts/respond.md

@@ -0,0 +1,27 @@
+# Respond to review feedback
+
+You are a coding agent in an isolated checkout of this repository, on the branch
+of an open pull request. New human feedback has been left on the PR or its tracker
+issue. Address it. You may only read and write files and run shell commands in
+this workspace. Do not use git: the factory owns commits and pushes.
+
+## The feedback
+Read `.ghostrail/feedback.md`. It contains the new comments (author and time),
+newest work last. Treat it as the review to act on.
+
+## What to do
+1. Read the feedback and the current state of the branch.
+2. Make the changes it asks for, matching the surrounding code and tests.
+3. Run the project's lint, typecheck, and unit-test commands and fix what you touched.
+4. If a comment is a question rather than a change request, answer it in your result
+   (see `blocked`) instead of guessing.
+
+## Reporting your result (required, do this last)
+Write a JSON file at `.ghostrail/result.json` with exactly one of:
+
+- `{"status":"done","summary":"<what you changed in response>"}`
+- `{"status":"blocked","questions":"<what you need answered>"}`
+- `{"status":"failed","error":"<why>"}`
+- `{"status":"noop"}`
+
+On `done` the factory commits and pushes to the PR branch and posts a summary.

package/templates/code-local/prompts/triage.md

@@ -0,0 +1,51 @@
+# Triage an issue
+
+You are triaging an issue in an isolated checkout of this repository. Your job is
+NOT to fix it: it is to decide whether the issue is too large to fix in one pass
+and, if so, propose how to break it into smaller, ordered sub-issues. Do not use
+git and do not change any source files except the two output files below.
+
+## The issue
+- ID: {{id}}
+- Title: {{title}}
+- Link: {{url}}
+
+## What to do
+1. Read the issue and enough of the codebase to judge its scope.
+2. Decide:
+   - **Atomic** — a single, focused change a coding agent can do in one pass.
+   - **Too large** — spans several independent changes, or mixes unrelated
+     concerns. Propose 2 to 6 sub-issues, each independently shippable, ordered so
+     that dependencies come first.
+3. Write the plan to `.ghostrail/triage.json` (schema below).
+4. Write `.ghostrail/result.json` with `{"status":"done","summary":"<one line>"}`
+   when you produced a plan, or `{"status":"blocked","questions":"<what you need>"}`
+   if you genuinely cannot decide without a human.
+
+## `.ghostrail/triage.json` schema
+
+Atomic (no split):
+
+```json
+{ "status": "noop", "reason": "<why it is already the right size>" }
+```
+
+Split into sub-issues:
+
+```json
+{
+  "status": "split",
+  "reason": "<why it needs splitting>",
+  "subIssues": [
+    { "title": "First, self-contained step", "description": "<what and why>" },
+    { "title": "Second step", "description": "<...>", "dependsOn": [0] }
+  ]
+}
+```
+
+- `dependsOn` lists the indices of earlier sub-issues (0-based, all strictly
+  less than the current one) that must be done first.
+- Keep titles imperative and specific. Each sub-issue should stand on its own.
+
+The factory creates the sub-issues (unassigned) and a human assigns each to the
+bot to start work; the parent leaves the triage queue.

package/templates/content-loop/ghostrail.toml

@@ -13,8 +13,8 @@ base_branch = "main"
 
 [source]
 kind = "linear"
-project = "TJ"                 # your Linear team key
-eligible = { state = "Todo", label = "draft", unassigned = true }
+team = "TJ"                 # your Linear team key
+eligible = { state = "Todo", label = "draft", assignee = "unassigned" }
 
 [agent]
 kind = "claude-code"
@@ -34,3 +34,6 @@ timeout = "30m"
 open_pr = true
 draft = true                   # content PRs open as drafts
 auto_merge = false
+
+[respond]                      # fold PR + tracker feedback back into the draft
+prompt = "prompts/respond.md"

package/templates/content-loop/prompts/respond.md

@@ -0,0 +1,25 @@
+# Respond to feedback on a draft
+
+You are a writing agent in an isolated checkout of this repository, on the branch
+of an open draft pull request. New human feedback has been left on the PR or its
+tracker issue. Revise the draft to address it. You may only read and write files
+and run shell commands in this workspace. Do not use git: the factory owns commits
+and pushes.
+
+## The feedback
+Read `.ghostrail/feedback.md`. It contains the new comments (author and time),
+newest work last. Treat it as the editorial review to act on.
+
+## What to do
+1. Read the feedback and the current draft on this branch.
+2. Revise the draft accordingly, keeping the established voice and format.
+3. If a comment is a question rather than a change, answer it in your result
+   (`blocked`) instead of guessing.
+
+## Reporting your result (required, do this last)
+Write a JSON file at `.ghostrail/result.json` with exactly one of:
+
+- `{"status":"done","summary":"<what you revised>"}`
+- `{"status":"blocked","questions":"<what you need answered>"}`
+- `{"status":"failed","error":"<why>"}`
+- `{"status":"noop"}`

package/templates/fix-bugs-local/ghostrail.toml

@@ -1,37 +0,0 @@
-# fix-bugs-local: a code factory on your own hardware, zero infrastructure.
-# Point it at a repo and a tracker label; it fixes bugs and opens PRs you merge.
-
-[factory]
-name = "fix-bugs"
-base_branch = "main"
-
-[source]
-kind = "linear"                # linear | github-issues (Phase 2)
-project = "TJ"                 # your Linear team key
-eligible = { state = "Todo", label = "factory", unassigned = true }
-
-[agent]
-kind = "claude-code"
-prompt = "prompts/fix-bug.md"
-# default allowed_tools = ["Read", "Edit", "Write", "Bash", "Grep", "Glob"]
-
-[backend]
-kind = "local-worktree"        # zero infrastructure; git worktree in place
-
-[gate]                         # the oracle: mirror your CI
-commands = [
-  "pnpm install --frozen-lockfile",
-  "pnpm lint",
-  "pnpm typecheck",
-  "pnpm test:unit",
-  "pnpm build",
-]
-
-[guardrails]
-max_items_per_run = 3
-budget_usd_per_item = 3
-timeout = "30m"
-
-[output]
-open_pr = true
-auto_merge = false             # a human owns every merge

package/templates/fix-bugs-local/prompts/fix-bug.md

@@ -1,27 +0,0 @@
-# Fix a bug
-
-You are a coding agent working in an isolated checkout of a repository. Fix the
-issue described below. You may only read and write files and run shell commands
-in this workspace. Do not use git: the factory owns commits, branches, and PRs.
-
-## The issue
-- ID: {{id}}
-- Title: {{title}}
-- Link: {{url}}
-
-## What to do
-1. Reproduce and locate the bug.
-2. Make the smallest correct fix.
-3. Add or update unit tests that cover it.
-4. Keep the change focused; do not refactor unrelated code.
-
-## Reporting your result (required, do this last)
-Write a JSON file at `.ghostrail/result.json` with exactly one of these shapes:
-
-- Success: `{"status":"done","summary":"<what you changed, one paragraph>"}`
-- Needs a human decision: `{"status":"blocked","questions":"<the decision you need>"}`
-- Could not fix it: `{"status":"failed","error":"<why>"}`
-- No change needed: `{"status":"noop"}`
-
-The factory reads this file to decide what to do, then runs your CI gate and, if
-it passes, opens a pull request for a human to review and merge.