Forge out of the core: an event source and an output destination like any other #1657
Notifications
Due Date
No due date set.
Depends on
Reference: sam/archie#1657
Reference in new issue
Block a user
Core workflow code assumes a forge: TaskContext.Forge and Trees, Task owner/repo/issue_number coordinates, IsForgeBacked branches (15 sites), forge calls from steps (11 sites), PR-shaped statuses (pr_open). AGENTS.md now says a forge is one event source and one output destination among many.
Wanted: forge intake is an event source like webhooks/schedules/chat; forge writes (comment, PR, close, push) are output destinations a step delivers to, configured like any other; task coordinates are generic subject references, not owner/repo/issue.
Done when: a workflow with no forge anywhere runs end to end with no forge-shaped field, status or branch in its path, and the forge integration lives behind the same destination/source interfaces as the others. Split into child beads before starting; ijmpz (test-run deliveries) is the first slice.
Imported from beads
archie-core-x1qxc· GitHub #1801 · type epic · priority P2 · created 2026-10-18archie's PRD is ready -- awaiting your go/no-go.
PRD: Forge out of the core — an event source and an output destination like any other
Source: archie-core-x1qxc / GitHub #1801 · type epic · P2 · created 2026-10-18
Drafted against: the tree at CHANGELOG [1.61.3] (2026-11-08), not against the epic text.
1. Problem
Core workflow code treats "there is a forge, and this task came from one" as a single fact derived from a string. That fact is read in three places it has no business being read, and it is missing in a fourth where it is needed.
1. Forge-backedness is inferred, not modelled.
Task.IsForgeBacked()isSource != "chat" && Source != "test"(internal/domain/workflow/task/task.go:173).Sourceis written by exactly one place:InsertChatTask(internal/infrastructure/postgres/queries/tasks.sql:60-100), which hardcodessource='chat'or'test'. Every other task takes the column defaultsource='forge'(migrations/0001_state_store.sql:46).InsertChatTaskis also the writer for binding dispatches:Store.EnqueueBindingTaskcallsinsertChatTaskdirectly (internal/infrastructure/postgres/store.go:234). So a webhook-dispatched event task on a repository is labelledsource='chat'and is therefore not forge-backed:forge.comment/forge.close-issuesilently return nil (control_steps.go:104,133);notify()(the approval notice) never posts (feasibility.go:12);<task source="chat">andtask.kindrenders "chat-originated task" (steps.go:181-199), so the agent is told its repository event is a chat message;repo.open-prstill callsCreatePRunconditionally and setspr_open(steps.go:147-167) — the one branch that only gatesLinkBranchonIsForgeBacked.13 call sites read this predicate today (the epic says 15):
feasibility.go:12;steps.go:129,147,181,189,196;control_steps.go:104,133;daemon/daemon.go:1383,1600;archiegateway/chat_tasks.go:28;taskactions/store.go:23;webui/tasks_handlers.go:205.2. Forge absence is emulated, not absent.
[forge] type = "none"(deployments/standalone.toml:33-35) wiresforge.NewNoop(internal/forge/noop.go), whose every write returnsnil/0. A forge write in a forge-free install reports success while doing nothing. Nothing tests this:grep NoopForge internal/**/*_test.go→ no matches. The only place absence is caught isarchied/repository_access.go:133-137, which failsOperationPRwithforge_unavailable— writes reached any other way are silent.3. Forge writes are hardcoded in steps. 10
tc.Forge.*calls plustc.Trees.Push(repo_steps.go:162):steps.go:133,149,157,control_steps.go:107,136,feasibility.go:13,remediate.go:142,review_steps.go:97,prreview_stages.go:753,761.workflow.Forger(workflow.go:29-46) has six methods; the seventh,CreateIssue, exists only on therecordedForgewrapper intest_run.goand is unreachable through the interface.4. Task coordinates are forge coordinates.
Task.Owner/Repo/IssueNumber(task/task.go:38-40) → protostate.v1.Taskfields 2/3/4; columnsowner,repo,issue_numberNOT NULL(0001_state_store.sql:24-26); unique indextasks_current_item_key (org_id, identity, owner, repo, issue_number) WHERE handoff_to_task_id IS NULL(0068_task_handoff_runs.sql:9-10); ~56 non-generated Go references to.IssueNumber. A repo-less chat task still gets a synthetic forge-shaped issue number from thechat_issue_numberssequence (0045_chat_issue_numbers.sql,InsertChatTask'sWITH numberCTE).5.
pr_openis load-bearing, not cosmetic. It guards remediation (BeginRemediationTask,PromotePendingReview,SetReviewCursors,ListOpenPRs—queries/tasks.sql:223,247,262,300), drives the operator action table (taskstate.Actions(StatusPROpen)→ Merge/OpenPR/OpenIssue), stats (events.sql:55,stats.pb.go:30), canary release statuses (releaseupdate/canary_dashboard.go:28) and the UI status catalogue.Three corrections the epic needs before anyone starts
a) The stated first slice is already shipped — before the epic was created.
ijmpz(test-run deliveries) landed in 1.53.0 on 2026-10-11: CHANGELOG line 164 "Test runs suppress forge and push writes and record what they would have done"; code isworkflow.Deliveries/RecordDeliveries(test_run.go),events.KindDeliveryRecorded, egress recording (egress/proxy.go:101-110,397-404), call siteagentworker/task_execution.go:297-299. The epic is dated a week later and still names it first. Closeijmpzas shipped and rebuild the slice list from what remains.b) "Behind the same source/destination interfaces as the others" — the others have no such interface. Intake is four unrelated mechanisms: webhook captures → bindings; schedules →
scheduling.JobSource/Runner→ a capture → binding; chat → gateway →EnqueueChatTask; forge →daemon.IssueSourcepoller (daemon.go:251-261, a struct, not an interface) → straight to NATSworkintakesubjects (daemon.go:1411+), bypassing captures and bindings entirely.grep 'type (EventSource|Source|Intake|Trigger|Destination|Sink) interface' internal/**.goreturns exactly one hit:scheduling.Sink(internal/domain/scheduling/contract.go:102). Half this epic is inventing the interface, not refactoring an existing one — a design decision that needs to be written down, not discovered mid-implementation.c) "Done when a workflow with no forge runs end to end" is already true, and therefore is not a test.
TestRepoLessTaskRunsTriageFromAPrompt(triage_repo_optional_test.go) runs the shippedtriageworkflow withrepository: optionaltocompletedin a scratch workspace with no forge. It gets there by declaringSource: SourceChat. So the acceptance criterion must be an artefact that fails today (§4).Bonus finding that changes the shape of the fix:
message.sendis the only non-forge output step, and it is not inrepoFreeStepTypes(definition.go:37-40), socheckTypedStep(step_flow.go:88) refuses it in any workflow whose repository is notrequired— whileWORKFLOWS.md:229-244documents it as "runs without a repository" and describes a scheduled message workflow whose only step it is. No test mentionsmessage.send. Net: a repository-less workflow can currently deliver nowhere except the two forge steps — precisely the ones a forge-free install must not use. Makingmessage.send(and the forge writes) destination steps is the same change.2. Proposed solution
Three separable pieces, in this order. Each is a slice that leaves the tree working.
2.1 Subject: provenance and identity, decoupled (slice 1)
Add a generic subject reference written by whichever source created the task, and stop deriving behaviour from
Source:subject_kind text NOT NULL DEFAULT '',subject_ref text NOT NULL DEFAULT '',subject_meta jsonb; backfillforge:issuefromsource='forge'rows andchat:conversation/test:draftelsewhere;subject_ref=owner/repo#numberor the existing synthetic number for old chat rows.(org, identity, owner, repo, issue_number)to(org_id, identity, subject_kind, subject_ref)wheresubject_ref <> ''; the legacy index is kept for forge rows until the worktree key is revisited (§2.5).IsForgeBacked()is deleted and replaced withSubject.Is(SubjectForgeIssue)at the 13 call sites.Task.Sourcebecomes pure provenance (webhook|schedule|chat|forge|test), never a behaviour switch.chat_issue_numbersand theInsertChatTaskCTE go away; the insert becomes a plainInsertTasktaking the subject. The synthetic-number base disappears.webhook:captureand is not forge-backed by accident — its forge writes are then governed by destinations (§2.2), not by its intake label.2.2 Destination: one door for outward effects (slice 2)
The run already has the door —
workflow.Deliveries(test_run.go), whoseRecordis what a test run does instead of delivering. Promote it from a recorder to the destination contract:nilperforms; a recording implementation records (existing); a failing implementation replacesNoopForgefor writes and returns a named error (no destination configured for forge), killing defect 2.config.Operations()(clone|push|pr),config.ForgeConnection.Permits,daemon.RepositoryAccess{Repository, Connection, Trees, Forge},Daemon.Repository(task, operation)(daemon/repository_access.go:25-49), re-resolved at each call (archied/repository_access.go:28-77), reached from the container throughforgerpc/worktreerpcwith a run credential. Nothing new is invented here: the destination is(connection, operation), which is the vocabulary the dashboard already edits (CHANGELOG 1.61.3).forge.comment→output.comment,forge.close-issue→output.close,repo.open-pr→output.open-change(same PR payload),repo.commit's implicitpush: true→ an explicitoutput.push, andmessage.sendreclassified asoutput.message— a destination step that no longer requires a worktree.NeedsRepository:NeedsDestination(stepType), a workflow-leveldestinations:declaration (defaulting to the repository binding's connection), and a refusal naming the step and the workflow when a destination step appears in a workflow that declares none. A forge-free workflow then cannot contain a forge write, instead of silently no-oping.TaskContext.ForgeandTaskContext.Trees.Pushleave the step library; the review/remediate pipelines keep calling their forge client directly (see §5).2.3 Source: forge intake becomes a capture (slice 3)
Schedules already do the right thing —
scheduleFirerrecords asource.ScheduleFiredcapture and a binding dispatches it (app/archied/scheduling.go:193-201). Webhooks already produce captures. Forge is the only source that bypasses captures and bindings and publishes straight to NATS. MakepollNATSemit a capture (forge:issuepayload, built-in mapping/event type, as0066_mapping_built_in.sqlalready supports for schedules) and let a binding dispatch it. Forge then is an event source like the others in the only sense the code has: it produces an event that routing consumes. Credentials stay inconfig.ForgeConnection— moving them to the control plane is a separate decision.2.4 Status vocabulary (slice 4, optional — recommend deferring)
pr_openstays. AddTask.AwaitingOn(the delivery kind that the run is waiting on, e.g.forge.pull-request) in the same migration as the subject, set whereOpenPRruns, read bytaskstate.Actionsand the UI link builder. Renaming the persisted status is a migration plus an operator-action change plus stats plus reconcile plus canary statuses; it buys nothing the epic's acceptance criteria need, because a forge-free run endscompletedand never touchespr_open.2.5 Worktree key (slice 1b, deferrable — recommend a separate issue)
worktree.Dir(owner, repo, issue)→issue-NandValidCoordinates(worktree/worktree.go:66-84) are what legitimately keepowner/repoas optional repository coordinates. Repo-less tasks already usePrepareScratch(task.ID)and never touch it. Generalising the directory key fromissue intto a subject string touches on-disk paths for existing installs (the legacy-directory migration), so it does not belong in the slice that has to prove a repo-less run works.Decisions the operator owns
Subject{Kind,Ref,Fields}(written by the source) + keepOwner/Repoas optional repository coordinates +AwaitingOn; unique key(org, identity, subject_kind, subject_ref). Do not try to express the subject as an opaque ref that also serves worktree naming — that is slice 1b.pr_openafter forge writes leave the step library, as its own issue. AddAwaitingOnnow; keep the string.pr-review,remediate, the review gate and PR reconcile are forge work by nature; the epic needs one forge-free workflow, not four.Process
The child slices must exist in the Gitea tracker before implementation (
AGENTS.md: "an issue is the plan"). The beads ids cited by the epic (ijmpz) leave no trace in the tree, so "split into child beads before starting" cannot be verified here — create the 4 slices (0: closeijmpzas shipped; 1: subject; 1b: worktree key; 2: destination; 3: forge-through-bindings) and drop the stale reference.3. Files and components affected
Schema / store
internal/infrastructure/postgres/migrations/0069_task_subject.sql(new): subject columns, backfill, unique-index swap.internal/infrastructure/postgres/queries/tasks.sql:InsertChatTask→InsertTask(subject_kind, subject_ref, subject_meta, …);EnqueueIssuestampsforge:issue;ListTaskSummaries,TaskByIssue,Unclaimed/ClaimByIssueprojections.internal/infrastructure/postgres/postgresdb/*.sql.go: regenerated.internal/infrastructure/postgres/store.go:EnqueueChatTask,EnqueueBindingTask,EnqueueIssue,taskFromRow.Wire
proto/state/v1/types.proto:Task.subject_kind = 53,subject_ref = 54,subject_meta_json = 55,awaiting_on = 56; regenerateinternal/contracts/state/v1.internal/infrastructure/staterpc/values.go:63,102.Domain
task/task.go:Subjecttype, deleteIsForgeBacked,HasRepositoryunchanged.workflow.go: deleteTaskContext.Forge,Forger; addDestination;TaskContext.Deliveriesreshaped.test_run.go:recordDeliveriesbecomes the recording destination;recordedForge/recordedTreescollapse into one wrapper.steps.go,control_steps.go,feasibility.go,repo_steps.go,review_steps.go,remediate.go,prreview_stages.go,step_flow.go,definition.go,task/interface.go: step renames,NeedsDestination,destinations:key.internal/forge/noop.go: writes return a named error (or the noop is deleted andarchiedwires an unavailable destination).App / wiring
internal/daemon/daemon.go: 1383, 1600;pollNATS→ capture;closeResolvedIssue;forgeFor/treesForbecome destination resolution.internal/daemon/repository_access.go,internal/app/archied/repository_access.go,internal/app/archied/bootstrap.go,scheduling.go,forgerpc/forgerpc.go,worktreerpc/worktreerpc.go,messagerpc/messagerpc.go.internal/domain/taskactions/service.go(+infrastructure/taskactions/store.go:23):ForgeBacked→ subject/destination.internal/app/archiegateway/chat_tasks.go:28,internal/webui/tasks_handlers.go:205,internal/releaseupdate/canary_dashboard.go:28.UI / docs
ui/: task list source label,taskURLsauthorisation, action buttons keyed on status (unchanged ifpr_openstays).WORKFLOWS.md: step type table (output.*),task.kindvocabulary (WORKFLOWS.md:72currently offers only "GitHub issue" or "chat-originated task"), and the repository-free classification (fixing themessage.senddivergence).CHANGELOG.md,AGENTS.md(no change needed — it already states the target).4. Acceptance criteria
Each is a test or a grep that fails on today's tree.
A1 — The artefact that fails today.
TestWebhookDispatchedRepoLessWorkflowRunsWithNoForge: a webhook binding dispatches arepository: noneworkflow (agent.run→workflow.finish) with no forge configured. Asserts: the task row hassubject_kindnaming the webhook capture and emptyowner/repoand no synthetic issue number; the recorded fake forge sees zero calls; the run reachescompleted; the agent's mission is framed from the subject, not<task source="chat">. Fails today on every row/framing assertion (source='chat', synthetic number,<task source="chat">).A2 — Forge-free install never reports a forged success.
TestForgeFreeInstallRefusesForgeDelivery: with[forge] type = "none", a workflow containing a forge destination step is refused at save with an error naming the step and the workflow; a task pinned to such a definition before the connection was removed parks with a named error instead of completing. Fails today:NoopForgereturns nil and the run completes.A3 — Intake label stops deciding behaviour.
TestBindingDispatchedRepoTaskDelivers: a binding-dispatched task on a configured repository running a comment step posts the comment (or fails with a named error when no destination is configured) and its mission block says<issue …>. Fails today: the comment silently no-ops and the mission sayssource="chat".A4 —
IsForgeBackedis gone.grep -r 'IsForgeBacked' internal/ cmd/ ui/returns nothing;grep -r 'tc\.Forge' internal/domain/workflow/*.go(non-test) returns nothing outside the review pipelines listed in §5.A5 — Provenance is modelled. Every task-creation path writes a non-empty
subject_kind; a unit test covers each of the five creators (EnqueueIssue,InsertTask/chat,EnqueueBindingTask,workflow.call, test run).A6 — Recording still records everything. The existing
test_run_test.gotable (6 forge methods + push) is extended to the destination vocabulary and still passes: a test run records a "would …" event for every delivery and performs none.A7 — No new service.
proto/gains fields only, no newproto/<service>; no new binary incmd/; sqlc and protobuf regenerated and committed in the same change.A8 — Migration is reversible and backfilled. Goose down restores the old columns/index; a copy-restored database yields
forge:issuefor formersource='forge'rows andchat:conversationfor former chat test rows, withpr_openand terminal tasks unchanged.5. Explicit non-goals
pr_open/merged/rejectedin this epic. Forge-free runs endcompletedand never reach them; the rename is its own issue (Q2).pr-review,remediate, the review gate and PR reconcile stay forge-shaped. They keep calling their forge client directly throughreview_steps.go/prreview_stages.go/remediate.go; only the shared step library is re-plumbed.vocabulary.go:24-34); this epic does not add a destination-provider framework.AGENTS.md, old rows are backfilled and old spellings deleted; there is no dual-read path.owner/repo/issuegone from disk too./approve,/stop, outcome posting,gateway.ChatTaskStatuskeep working; only the encoding of "chat task" moves fromsourcetosubject.6. Estimated diff size
Across 4-6 PRs. This is far past the ~100-line threshold
AGENTS.mdsets for "stop and assess", and the migration + proto + workflow step contract are all in that file's list of seams that require tests — which is why it needs the PRD and the tracker slices before the first line of code.7. What I verified and what I did not
Verified by reading the tree: every line reference and count above; the 13
IsForgeBackedcall sites and 11 forge-write call sites (counted, not assumed);InsertChatTaskas the single writer for both chat and binding tasks;sourcedefaulting toforge;NoopForgereturning nil on every write with no test referencing it; the one-interface-only result of the source/destination interface grep;message.sendabsent fromrepoFreeStepTypeswhile documented as repository-free; the 1.53.0 changelog entry andtest_run.go/RecordDeliveries/egress.RecordOptionscode; the(connection, operation)resolution path that a destination can reuse.Not verified: whether any e2e check (
e2e/checks/*.cjs— 29 files, none obviously repo-less) covers a repository-less, forge-free run end to end; I did not run the e2e stack, did not rungo test, and had no tracker access to confirm the epic's children or the current open-issue/label state in Gitea.Decide in chat or on the dashboard.