Forge out of the core: an event source and an output destination like any other #1657

Open
opened 2026-10-27 13:41:16 +00:00 by sam · 1 comment
Owner

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-18

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-18_
sam added the mediumepic labels 2026-10-27 13:41:16 +00:00
sam self-assigned this 2026-10-27 13:41:16 +00:00
Author
Owner

archie'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() is Source != "chat" && Source != "test" (internal/domain/workflow/task/task.go:173). Source is written by exactly one place: InsertChatTask (internal/infrastructure/postgres/queries/tasks.sql:60-100), which hardcodes source='chat' or 'test'. Every other task takes the column default source='forge' (migrations/0001_state_store.sql:46).

InsertChatTask is also the writer for binding dispatches: Store.EnqueueBindingTask calls insertChatTask directly (internal/infrastructure/postgres/store.go:234). So a webhook-dispatched event task on a repository is labelled source='chat' and is therefore not forge-backed:

  • forge.comment / forge.close-issue silently return nil (control_steps.go:104,133); notify() (the approval notice) never posts (feasibility.go:12);
  • the agent's mission is framed <task source="chat"> and task.kind renders "chat-originated task" (steps.go:181-199), so the agent is told its repository event is a chat message;
  • yet repo.open-pr still calls CreatePR unconditionally and sets pr_open (steps.go:147-167) — the one branch that only gates LinkBranch on IsForgeBacked.

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) wires forge.NewNoop (internal/forge/noop.go), whose every write returns nil/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 is archied/repository_access.go:133-137, which fails OperationPR with forge_unavailable — writes reached any other way are silent.

3. Forge writes are hardcoded in steps. 10 tc.Forge.* calls plus tc.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 the recordedForge wrapper in test_run.go and is unreachable through the interface.

4. Task coordinates are forge coordinates. Task.Owner/Repo/IssueNumber (task/task.go:38-40) → proto state.v1.Task fields 2/3/4; columns owner,repo,issue_number NOT NULL (0001_state_store.sql:24-26); unique index tasks_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 the chat_issue_numbers sequence (0045_chat_issue_numbers.sql, InsertChatTask's WITH number CTE).

5. pr_open is 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 is workflow.Deliveries/RecordDeliveries (test_run.go), events.KindDeliveryRecorded, egress recording (egress/proxy.go:101-110,397-404), call site agentworker/task_execution.go:297-299. The epic is dated a week later and still names it first. Close ijmpz as 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.IssueSource poller (daemon.go:251-261, a struct, not an interface) → straight to NATS workintake subjects (daemon.go:1411+), bypassing captures and bindings entirely. grep 'type (EventSource|Source|Intake|Trigger|Destination|Sink) interface' internal/**.go returns 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 shipped triage workflow with repository: optional to completed in a scratch workspace with no forge. It gets there by declaring Source: SourceChat. So the acceptance criterion must be an artefact that fails today (§4).

Bonus finding that changes the shape of the fix: message.send is the only non-forge output step, and it is not in repoFreeStepTypes (definition.go:37-40), so checkTypedStep (step_flow.go:88) refuses it in any workflow whose repository is not required — while WORKFLOWS.md:229-244 documents it as "runs without a repository" and describes a scheduled message workflow whose only step it is. No test mentions message.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. Making message.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:

// internal/domain/workflow/task
type Subject struct {
    Kind   string         // "forge:issue", "webhook:capture", "schedule:firing", "chat:conversation", "workflow:call"
    Ref    string         // stable external identity: "acme/app#123", capture id, "schedule/run", conversation id
    Fields map[string]any // source-shaped payload: owner, repo, number, title, body, labels
}
  • Columns subject_kind text NOT NULL DEFAULT '', subject_ref text NOT NULL DEFAULT '', subject_meta jsonb; backfill forge:issue from source='forge' rows and chat:conversation/test:draft elsewhere; subject_ref = owner/repo#number or the existing synthetic number for old chat rows.
  • Uniqueness moves from (org, identity, owner, repo, issue_number) to (org_id, identity, subject_kind, subject_ref) where subject_ref <> ''; the legacy index is kept for forge rows until the worktree key is revisited (§2.5).
  • IsForgeBacked() is deleted and replaced with Subject.Is(SubjectForgeIssue) at the 13 call sites. Task.Source becomes pure provenance (webhook|schedule|chat|forge|test), never a behaviour switch.
  • chat_issue_numbers and the InsertChatTask CTE go away; the insert becomes a plain InsertTask taking the subject. The synthetic-number base disappears.
  • This is what fixes the binding-dispatch defect: a webhook task on a repository has subject webhook:capture and 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), whose Record is what a test run does instead of delivering. Promote it from a recorder to the destination contract:

type Delivery struct {
    Destination string // "forge", "messaging", "push"
    Operation   string // config.OperationPR / OperationPush / a messaging send
    Subject     task.Subject
    Repo        config.Repo
    Payload     map[string]any
}
type Destination interface { Deliver(ctx context.Context, d Delivery) error }
  • nil performs; a recording implementation records (existing); a failing implementation replaces NoopForge for writes and returns a named error (no destination configured for forge), killing defect 2.
  • The daemon side already resolves destinations per operation and per identity: 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 through forgerpc/worktreerpc with 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).
  • Step types: forge.comment → output.comment, forge.close-issue → output.close, repo.open-pr → output.open-change (same PR payload), repo.commit's implicit push: true → an explicit output.push, and message.send reclassified as output.message — a destination step that no longer requires a worktree.
  • Save-time validation mirrors NeedsRepository: NeedsDestination(stepType), a workflow-level destinations: 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.Forge and TaskContext.Trees.Push leave 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 — scheduleFirer records a source.ScheduleFired capture 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. Make pollNATS emit a capture (forge:issue payload, built-in mapping/event type, as 0066_mapping_built_in.sql already 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 in config.ForgeConnection — moving them to the control plane is a separate decision.

2.4 Status vocabulary (slice 4, optional — recommend deferring)

pr_open stays. Add Task.AwaitingOn (the delivery kind that the run is waiting on, e.g. forge.pull-request) in the same migration as the subject, set where OpenPR runs, read by taskstate.Actions and 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 ends completed and never touches pr_open.

2.5 Worktree key (slice 1b, deferrable — recommend a separate issue)

worktree.Dir(owner, repo, issue) → issue-N and ValidCoordinates (worktree/worktree.go:66-84) are what legitimately keep owner/repo as optional repository coordinates. Repo-less tasks already use PrepareScratch(task.ID) and never touch it. Generalising the directory key from issue int to 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

# Question Recommendation
Q1 Subject model Subject{Kind,Ref,Fields} (written by the source) + keep Owner/Repo as 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.
Q2 Status vocabulary Rename pr_open after forge writes leave the step library, as its own issue. Add AwaitingOn now; keep the string.
Q3 Forge intake shape Emit a capture from the poller so forge flows through mappings/bindings like schedules and webhooks. If the epic must be smaller, this slice is the one to cut — slices 1-2 alone satisfy the "done" criteria.
Q4 Scope of PR-shaped pipelines Out of scope. 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: close ijmpz as 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, …); EnqueueIssue stamps forge:issue; ListTaskSummaries, TaskByIssue, Unclaimed/ClaimByIssue projections.
  • 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; regenerate internal/contracts/state/v1.
  • internal/infrastructure/staterpc/values.go:63,102.

Domain

  • task/task.go: Subject type, delete IsForgeBacked, HasRepository unchanged.
  • workflow.go: delete TaskContext.Forge, Forger; add Destination; TaskContext.Deliveries reshaped.
  • test_run.go: recordDeliveries becomes the recording destination; recordedForge/recordedTrees collapse 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 and archied wires an unavailable destination).

App / wiring

  • internal/daemon/daemon.go: 1383, 1600; pollNATS → capture; closeResolvedIssue; forgeFor/treesFor become 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, taskURLs authorisation, action buttons keyed on status (unchanged if pr_open stays).
  • WORKFLOWS.md: step type table (output.*), task.kind vocabulary (WORKFLOWS.md:72 currently offers only "GitHub issue" or "chat-originated task"), and the repository-free classification (fixing the message.send divergence).
  • 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 a repository: none workflow (agent.run → workflow.finish) with no forge configured. Asserts: the task row has subject_kind naming the webhook capture and empty owner/repo and no synthetic issue number; the recorded fake forge sees zero calls; the run reaches completed; 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: NoopForge returns 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 says source="chat".

A4 — IsForgeBacked is 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.go table (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 new proto/<service>; no new binary in cmd/; 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:issue for former source='forge' rows and chat:conversation for former chat test rows, with pr_open and terminal tasks unchanged.


5. Explicit non-goals

  • No rename or reclassification of pr_open/merged/rejected in this epic. Forge-free runs end completed and 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 through review_steps.go/prreview_stages.go/remediate.go; only the shared step library is re-plumbed.
  • No moving forge credentials out of config/connections into a control-plane "source resource". Q3 deliberately stops at the capture boundary.
  • No new forge backends, no third-party source plugins, no plugin registry. Step-type providers already exist (vocabulary.go:24-34); this epic does not add a destination-provider framework.
  • No compatibility shims. Per AGENTS.md, old rows are backfilled and old spellings deleted; there is no dual-read path.
  • Not the worktree directory-key change (slice 1b) — unless the operator wants owner/repo/issue gone from disk too.
  • No change to chat behaviour: conversations, /approve, /stop, outcome posting, gateway.ChatTaskStatus keep working; only the encoding of "chat task" moves from source to subject.

6. Estimated diff size

Slice Hand-written With regenerated code
1 — Subject (+ migration, proto, 13 call sites, UI) ~630 ~900
1b — Worktree key ~250 ~250
2 — Destination (+ step renames, validation, wiring, WORKFLOWS.md) ~1,000 ~1,050
3 — Forge intake through captures/bindings ~350 ~370
4 — Status vocabulary (if taken) ~300 ~350
Total ~2,300-2,500 ~3,300-3,800

Across 4-6 PRs. This is far past the ~100-line threshold AGENTS.md sets 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 IsForgeBacked call sites and 11 forge-write call sites (counted, not assumed); InsertChatTask as the single writer for both chat and binding tasks; source defaulting to forge; NoopForge returning nil on every write with no test referencing it; the one-interface-only result of the source/destination interface grep; message.send absent from repoFreeStepTypes while documented as repository-free; the 1.53.0 changelog entry and test_run.go/RecordDeliveries/egress.RecordOptions code; 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 run go 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.

**archie'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()` is `Source != "chat" && Source != "test"` (`internal/domain/workflow/task/task.go:173`). `Source` is written by exactly one place: `InsertChatTask` (`internal/infrastructure/postgres/queries/tasks.sql:60-100`), which hardcodes `source='chat'` or `'test'`. Every other task takes the column default `source='forge'` (`migrations/0001_state_store.sql:46`). `InsertChatTask` is also the writer for **binding dispatches**: `Store.EnqueueBindingTask` calls `insertChatTask` directly (`internal/infrastructure/postgres/store.go:234`). So a webhook-dispatched event task on a **repository** is labelled `source='chat'` and is therefore not forge-backed: - `forge.comment` / `forge.close-issue` silently return nil (`control_steps.go:104,133`); `notify()` (the approval notice) never posts (`feasibility.go:12`); - the agent's mission is framed `<task source="chat">` and `task.kind` renders "chat-originated task" (`steps.go:181-199`), so the agent is told its repository event is a chat message; - yet `repo.open-pr` still calls `CreatePR` unconditionally and sets `pr_open` (`steps.go:147-167`) — the one branch that only gates `LinkBranch` on `IsForgeBacked`. 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`) wires `forge.NewNoop` (`internal/forge/noop.go`), whose every write returns `nil`/`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 is `archied/repository_access.go:133-137`, which fails `OperationPR` with `forge_unavailable` — writes reached any other way are silent. **3. Forge writes are hardcoded in steps.** 10 `tc.Forge.*` calls plus `tc.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 the `recordedForge` wrapper in `test_run.go` and is unreachable through the interface. **4. Task coordinates are forge coordinates.** `Task.Owner/Repo/IssueNumber` (`task/task.go:38-40`) → proto `state.v1.Task` fields 2/3/4; columns `owner`,`repo`,`issue_number` `NOT NULL` (`0001_state_store.sql:24-26`); unique index `tasks_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 the `chat_issue_numbers` sequence (`0045_chat_issue_numbers.sql`, `InsertChatTask`'s `WITH number` CTE). **5. `pr_open` is 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 is `workflow.Deliveries`/`RecordDeliveries` (`test_run.go`), `events.KindDeliveryRecorded`, egress recording (`egress/proxy.go:101-110,397-404`), call site `agentworker/task_execution.go:297-299`. The epic is dated a week later and still names it first. **Close `ijmpz` as 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.IssueSource` poller (`daemon.go:251-261`, a struct, not an interface) → straight to NATS `workintake` subjects (`daemon.go:1411+`), bypassing captures and bindings entirely. `grep 'type (EventSource|Source|Intake|Trigger|Destination|Sink) interface' internal/**.go` returns 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 shipped `triage` workflow with `repository: optional` to `completed` in a scratch workspace with no forge. It gets there by declaring `Source: SourceChat`. So the acceptance criterion must be an artefact that **fails today** (§4). **Bonus finding that changes the shape of the fix:** `message.send` is the only non-forge output step, and it is *not* in `repoFreeStepTypes` (`definition.go:37-40`), so `checkTypedStep` (`step_flow.go:88`) refuses it in any workflow whose repository is not `required` — while `WORKFLOWS.md:229-244` documents it as "runs without a repository" and describes a scheduled message workflow whose only step it is. No test mentions `message.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. Making `message.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`: ```go // internal/domain/workflow/task type Subject struct { Kind string // "forge:issue", "webhook:capture", "schedule:firing", "chat:conversation", "workflow:call" Ref string // stable external identity: "acme/app#123", capture id, "schedule/run", conversation id Fields map[string]any // source-shaped payload: owner, repo, number, title, body, labels } ``` - Columns `subject_kind text NOT NULL DEFAULT ''`, `subject_ref text NOT NULL DEFAULT ''`, `subject_meta jsonb`; backfill `forge:issue` from `source='forge'` rows and `chat:conversation`/`test:draft` elsewhere; `subject_ref` = `owner/repo#number` or the existing synthetic number for old chat rows. - Uniqueness moves from `(org, identity, owner, repo, issue_number)` to `(org_id, identity, subject_kind, subject_ref)` where `subject_ref <> ''`; the legacy index is kept for forge rows until the worktree key is revisited (§2.5). - `IsForgeBacked()` is deleted and replaced with `Subject.Is(SubjectForgeIssue)` at the 13 call sites. `Task.Source` becomes pure provenance (`webhook|schedule|chat|forge|test`), never a behaviour switch. - `chat_issue_numbers` and the `InsertChatTask` CTE go away; the insert becomes a plain `InsertTask` taking the subject. The synthetic-number base disappears. - This is what fixes the binding-dispatch defect: a webhook task on a repository has subject `webhook:capture` and 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`), whose `Record` is what a test run does instead of delivering. Promote it from a recorder to the destination contract: ```go type Delivery struct { Destination string // "forge", "messaging", "push" Operation string // config.OperationPR / OperationPush / a messaging send Subject task.Subject Repo config.Repo Payload map[string]any } type Destination interface { Deliver(ctx context.Context, d Delivery) error } ``` - `nil` performs; a recording implementation records (existing); a **failing** implementation replaces `NoopForge` for writes and returns a named error (`no destination configured for forge`), killing defect 2. - The daemon side already resolves destinations per operation and per identity: `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 through `forgerpc`/`worktreerpc` with 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). - Step types: `forge.comment` → `output.comment`, `forge.close-issue` → `output.close`, `repo.open-pr` → `output.open-change` (same PR payload), `repo.commit`'s implicit `push: true` → an explicit `output.push`, and `message.send` reclassified as `output.message` — a destination step that no longer requires a worktree. - Save-time validation mirrors `NeedsRepository`: `NeedsDestination(stepType)`, a workflow-level `destinations:` 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.Forge` and `TaskContext.Trees.Push` leave 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 — `scheduleFirer` records a `source.ScheduleFired` capture 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. Make `pollNATS` emit a capture (`forge:issue` payload, built-in mapping/event type, as `0066_mapping_built_in.sql` already 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 in `config.ForgeConnection` — moving them to the control plane is a separate decision. ### 2.4 Status vocabulary (slice 4, optional — recommend deferring) `pr_open` stays. Add `Task.AwaitingOn` (the delivery kind that the run is waiting on, e.g. `forge.pull-request`) in the same migration as the subject, set where `OpenPR` runs, read by `taskstate.Actions` and 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 ends `completed` and never touches `pr_open`. ### 2.5 Worktree key (slice 1b, deferrable — recommend a separate issue) `worktree.Dir(owner, repo, issue)` → `issue-N` and `ValidCoordinates` (`worktree/worktree.go:66-84`) are what legitimately keep `owner/repo` as optional repository coordinates. Repo-less tasks already use `PrepareScratch(task.ID)` and never touch it. Generalising the directory key from `issue int` to 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 | # | Question | Recommendation | |---|---|---| | Q1 | Subject model | `Subject{Kind,Ref,Fields}` (written by the source) + keep `Owner/Repo` as 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. | | Q2 | Status vocabulary | Rename `pr_open` **after** forge writes leave the step library, as its own issue. Add `AwaitingOn` now; keep the string. | | Q3 | Forge intake shape | Emit a capture from the poller so forge flows through mappings/bindings like schedules and webhooks. If the epic must be smaller, this slice is the one to cut — slices 1-2 alone satisfy the "done" criteria. | | Q4 | Scope of PR-shaped pipelines | Out of scope. `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: close `ijmpz` as 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, …)`; `EnqueueIssue` stamps `forge:issue`; `ListTaskSummaries`, `TaskByIssue`, `Unclaimed`/`ClaimByIssue` projections. - `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`; regenerate `internal/contracts/state/v1`. - `internal/infrastructure/staterpc/values.go:63,102`. **Domain** - `task/task.go`: `Subject` type, delete `IsForgeBacked`, `HasRepository` unchanged. - `workflow.go`: delete `TaskContext.Forge`, `Forger`; add `Destination`; `TaskContext.Deliveries` reshaped. - `test_run.go`: `recordDeliveries` becomes the recording destination; `recordedForge`/`recordedTrees` collapse 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 and `archied` wires an unavailable destination). **App / wiring** - `internal/daemon/daemon.go`: 1383, 1600; `pollNATS` → capture; `closeResolvedIssue`; `forgeFor`/`treesFor` become 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, `taskURLs` authorisation, action buttons keyed on status (unchanged if `pr_open` stays). - `WORKFLOWS.md`: step type table (`output.*`), `task.kind` vocabulary (`WORKFLOWS.md:72` currently offers only "GitHub issue" or "chat-originated task"), and the repository-free classification (fixing the `message.send` divergence). - `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 a `repository: none` workflow (`agent.run` → `workflow.finish`) with no forge configured. Asserts: the task row has `subject_kind` naming the webhook capture and empty `owner`/`repo` and **no synthetic issue number**; the recorded fake forge sees zero calls; the run reaches `completed`; 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: `NoopForge` returns 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 says `source="chat"`. **A4 — `IsForgeBacked` is 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.go` table (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 new `proto/<service>`; no new binary in `cmd/`; 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:issue` for former `source='forge'` rows and `chat:conversation` for former chat test rows, with `pr_open` and terminal tasks unchanged. --- ## 5. Explicit non-goals - **No rename or reclassification of `pr_open`/`merged`/`rejected` in this epic.** Forge-free runs end `completed` and 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 through `review_steps.go`/`prreview_stages.go`/`remediate.go`; only the shared step library is re-plumbed. - **No moving forge credentials out of config/connections into a control-plane "source resource".** Q3 deliberately stops at the capture boundary. - **No new forge backends, no third-party source plugins, no plugin registry.** Step-type providers already exist (`vocabulary.go:24-34`); this epic does not add a destination-provider framework. - **No compatibility shims.** Per `AGENTS.md`, old rows are backfilled and old spellings deleted; there is no dual-read path. - **Not the worktree directory-key change** (slice 1b) — unless the operator wants `owner/repo/issue` gone from disk too. - **No change to chat behaviour**: conversations, `/approve`, `/stop`, outcome posting, `gateway.ChatTaskStatus` keep working; only the encoding of "chat task" moves from `source` to `subject`. --- ## 6. Estimated diff size | Slice | Hand-written | With regenerated code | |---|---|---| | 1 — Subject (+ migration, proto, 13 call sites, UI) | ~630 | ~900 | | 1b — Worktree key | ~250 | ~250 | | 2 — Destination (+ step renames, validation, wiring, WORKFLOWS.md) | ~1,000 | ~1,050 | | 3 — Forge intake through captures/bindings | ~350 | ~370 | | 4 — Status vocabulary (if taken) | ~300 | ~350 | | **Total** | **~2,300-2,500** | **~3,300-3,800** | Across 4-6 PRs. This is far past the ~100-line threshold `AGENTS.md` sets 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 `IsForgeBacked` call sites and 11 forge-write call sites (counted, not assumed); `InsertChatTask` as the single writer for both chat and binding tasks; `source` defaulting to `forge`; `NoopForge` returning nil on every write with no test referencing it; the one-interface-only result of the source/destination interface grep; `message.send` absent from `repoFreeStepTypes` while documented as repository-free; the 1.53.0 changelog entry and `test_run.go`/`RecordDeliveries`/`egress.RecordOptions` code; 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 run `go 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._
sam added a new dependency 2026-11-14 14:45:13 +00:00
sam added the deferred label 2026-11-15 17:26:15 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#1657