diff --git a/.agents/plans/19-maintainability/README.md b/.agents/plans/19-maintainability/README.md new file mode 100644 index 00000000..88167346 --- /dev/null +++ b/.agents/plans/19-maintainability/README.md @@ -0,0 +1,42 @@ +# Maintainability after Flow 10 + +Preserve Session v5, host-observed validation, independent review, exact-artifact +qualification, and resumable publication. Reduce the places a maintainer must +change to preserve those guarantees. + +## First change + +- Share Node, package-pinned Bun, and frozen dependency installation through + `.github/actions/setup-project`. Ordinary CI, scheduled evals, and weekly + compatibility use the same setup. Jobs keep their names, runners, triggers, + permissions, checks, and checkout policy. +- Keep conditional patch qualification, Bun-only auditing, and publication's + registry/npm setup explicit. A shared action should not need a collection of + switches for these different contracts. +- Build tool status metadata once on a fresh response object. Remove forwarding + error and reviewer wrappers and the repeated validation coordinator argument. + Keep schema parsing, mutation cancellation, reviewer-only writes, and exact + completion replay at their existing boundaries. + +## Next changes, in order + +1. Move duplicated candidate preparation from the two release jobs into one + tested command. Keep historical release rules and immutable artifact checks + intact; compare every supported version's old and new commands before landing. +2. Give auto-drive presentation/timing a separate owner from execution authority. + Then separate native hook registration from lifecycle decisions. Extract one + cohesive responsibility at a time, without adding a second state ledger or + passing the entire coordinator into each module. +3. Make qualification status a single read-only command derived from existing + matrix, canary, archive, and publication records. Report the next unmet gate + and whether it is offline or requires an approved model dispatch. Preserve + failed attempts and original accounting; do not infer success from exit codes. +4. Consolidate maintainer instructions around those commands. Keep historical + evidence immutable and link it rather than copying operating receipts into + additional status files. + +Each follow-up should remove duplicated policy or reduce independent mutable +state, retain the original behavioral controls, and pass normal CI. File moves +alone, larger line limits, broader test timeouts, and removed safety checks do +not count as simplification. Runtime changes still follow release qualification; +this maintenance PR neither publishes a version nor starts paid evaluations. diff --git a/.github/actions/setup-project/action.yml b/.github/actions/setup-project/action.yml new file mode 100644 index 00000000..5a292757 --- /dev/null +++ b/.github/actions/setup-project/action.yml @@ -0,0 +1,16 @@ +name: Set up Flow project +description: Install the CI Node runtime, package-pinned Bun, and locked dependencies. +runs: + using: composite + steps: + - name: Set up Node + uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + with: + node-version: 26 + - name: Set up Bun + uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 + with: + bun-version-file: package.json + - name: Install dependencies + shell: bash + run: bun install --frozen-lockfile diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 28924175..5e8554de 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -66,18 +66,8 @@ jobs: with: fetch-depth: 0 - - name: Set up Node - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 - with: - node-version: 26 - - - name: Set up Bun - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 - with: - bun-version: 1.4.0 - - - name: Install dependencies - run: bun install --frozen-lockfile + - name: Set up project toolchain + uses: ./.github/actions/setup-project - name: Run checks run: bun run check @@ -142,18 +132,8 @@ jobs: - name: Check out repository uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - name: Set up Node - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 - with: - node-version: 26 - - - name: Set up Bun - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 - with: - bun-version: 1.4.0 - - - name: Install dependencies - run: bun install --frozen-lockfile + - name: Set up project toolchain + uses: ./.github/actions/setup-project - name: Run platform filesystem checks run: bun test tests/workspace-persistence.test.ts tests/source-identity.test.ts tests/flow-leadership.test.ts tests/test-results.test.ts tests/validation-capture.test.ts @@ -164,18 +144,8 @@ jobs: - name: Check out repository uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - name: Set up Node - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 - with: - node-version: 26 - - - name: Set up Bun - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 - with: - bun-version: 1.4.0 - - - name: Install dependencies - run: bun install --frozen-lockfile + - name: Set up project toolchain + uses: ./.github/actions/setup-project - name: Run live OpenCode smoke run: bun run smoke:live diff --git a/.github/workflows/evals.yml b/.github/workflows/evals.yml index 48a537f6..ef4211ab 100644 --- a/.github/workflows/evals.yml +++ b/.github/workflows/evals.yml @@ -49,18 +49,8 @@ jobs: # the job only reads the checkout, runs the eval, and uploads an artifact. persist-credentials: false - - name: Set up Node - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 - with: - node-version: 26 - - - name: Set up Bun - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 - with: - bun-version: 1.4.0 - - - name: Install dependencies - run: bun install --frozen-lockfile + - name: Set up project toolchain + uses: ./.github/actions/setup-project # Absent credentials are a configuration state, not a failure: a fork and a # freshly cloned repository both have none, and failing the schedule there diff --git a/.github/workflows/opencode-compatibility.yml b/.github/workflows/opencode-compatibility.yml index 835ffae9..a67f889a 100644 --- a/.github/workflows/opencode-compatibility.yml +++ b/.github/workflows/opencode-compatibility.yml @@ -15,18 +15,8 @@ jobs: - name: Check out repository uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - name: Set up Node - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 - with: - node-version: 26 - - - name: Set up Bun - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 - with: - bun-version: 1.4.0 - - - name: Install dependencies - run: bun install --frozen-lockfile + - name: Set up project toolchain + uses: ./.github/actions/setup-project - name: Resolve the latest OpenCode 2 release run: | diff --git a/src/platform/opencode/tools.ts b/src/platform/opencode/tools.ts index 720fa865..4a40c291 100644 --- a/src/platform/opencode/tools.ts +++ b/src/platform/opencode/tools.ts @@ -82,10 +82,6 @@ type ToolOptions = Readonly<{ | undefined; }>; -function toolError(error: unknown): FlowToolResponse { - return errorResponse(error); -} - function bestEffort(read: () => Value): Value | undefined { try { return read(); @@ -100,17 +96,13 @@ function withAutoContext( view?: string, sessionID?: string, ): FlowToolResponse { - let workflowData = response.workflowData; const reviewer = options.readReviewerConfiguration?.() ?? options.reviewerConfiguration; - if (reviewer) { - workflowData = { - ...workflowData, - reviewerConfiguration: flowReviewerStatus(reviewer), - }; - } - workflowData = { - ...workflowData, + const workflowData: Record = { + ...response.workflowData, + ...(reviewer + ? { reviewerConfiguration: flowReviewerStatus(reviewer) } + : {}), modelConfiguration: flowModelStatus( options.readPlanningModel?.(), sessionID ? options.readCodingModel?.(sessionID) : undefined, @@ -118,38 +110,30 @@ function withAutoContext( ), }; if (options.runtimeIdentity) - workflowData = { - ...workflowData, - runtimeIdentity: options.runtimeIdentity, - }; + workflowData.runtimeIdentity = options.runtimeIdentity; const timing = view === "detail" ? bestEffort(() => options.autoTimingSnapshot?.()) : undefined; - if (timing) workflowData = { ...workflowData, autoTiming: timing }; + if (timing) workflowData.autoTiming = timing; const continuation = sessionID ? bestEffort(() => options.autoContinuationSnapshot?.(sessionID)) : undefined; - if (continuation) workflowData = { ...workflowData, autoDrive: continuation }; + if (continuation) workflowData.autoDrive = continuation; const support = bestEffort(() => options.autoContinuationSupport?.()); if (support === "supported" || support === "unsupported") { - workflowData = { - ...workflowData, - autoContinuation: { - scope: "current-plugin-process", - support, - ...(support === "unsupported" - ? { - reason: "host-request-attribution-unavailable", - recovery: "Drive each feature with /flow-run.", - } - : {}), - }, + workflowData.autoContinuation = { + scope: "current-plugin-process", + support, + ...(support === "unsupported" + ? { + reason: "host-request-attribution-unavailable", + recovery: "Drive each feature with /flow-run.", + } + : {}), }; } - return workflowData === response.workflowData - ? response - : { ...response, workflowData }; + return { ...response, workflowData }; } export function createTools(options: ToolOptions): FlowTools { @@ -169,27 +153,15 @@ export function createTools(options: ToolOptions): FlowTools { ), ); } catch (error) { - return toolError(error); + return errorResponse(error); } } function executeMutation( - context: FlowToolContext, - validation: ValidationCaptureCoordinator, - handler: (flow: WorkspaceFlowService) => Promise, - ): Promise { - validation.cancel(context.sessionID); - return execute(context, handler); - } - - function executeReviewerMutation( context: FlowToolContext, handler: (flow: WorkspaceFlowService) => Promise, - replayHandler: (flow: WorkspaceFlowService) => Promise, ): Promise { - if (context.agent !== "flow-reviewer") { - return execute(context, replayHandler); - } + options.validation.cancel(context.sessionID); return execute(context, handler); } @@ -247,7 +219,7 @@ export function createTools(options: ToolOptions): FlowTools { description: "Create or replace the active draft plan.", schema: PlanSaveInputSchema, execute: (args, context) => - executeMutation(context, options.validation, (workspace) => + executeMutation(context, (workspace) => workspace.planSave(args, requestAuthority(context.sessionID)), ), }), @@ -255,7 +227,7 @@ export function createTools(options: ToolOptions): FlowTools { description: "Approve the current draft plan.", schema: PlanApproveInputSchema, execute: (args, context) => - executeMutation(context, options.validation, (workspace) => + executeMutation(context, (workspace) => workspace.planApprove(args, requestAuthority(context.sessionID)), ), }), @@ -264,17 +236,13 @@ export function createTools(options: ToolOptions): FlowTools { "Record a same-goal reversible prerequisite repair after a failed canonical gate, without an amendment count limit. This does not change the approved plan or bypass review.", schema: PlanAmendInputSchema, execute: (args, context) => - executeMutation(context, options.validation, (workspace) => - workspace.planAmend(args), - ), + executeMutation(context, (workspace) => workspace.planAmend(args)), }), flow_run_start: defineFlowTool({ description: "Start one runnable approved feature.", schema: RunStartInputSchema, execute: (args, context) => - executeMutation(context, options.validation, (workspace) => - workspace.runStart(args), - ), + executeMutation(context, (workspace) => workspace.runStart(args)), }), flow_validation_start: defineFlowTool({ description: @@ -308,7 +276,7 @@ export function createTools(options: ToolOptions): FlowTools { }, }; } catch (error) { - return toolError(error); + return errorResponse(error); } }, }), @@ -317,19 +285,17 @@ export function createTools(options: ToolOptions): FlowTools { "Create one independent review assignment using current applicable validation.", schema: ReviewStartInputSchema, execute: (args, context) => - executeMutation(context, options.validation, (workspace) => - workspace.reviewStart(args), - ), + executeMutation(context, (workspace) => workspace.reviewStart(args)), }), flow_feature_complete: defineFlowTool({ description: "Submit a pending review result; only the reviewer may create a new completion, while exact accepted requests remain replayable for an active Session v5 workflow.", schema: FeatureCompleteInputSchema, execute: (args, context) => - executeReviewerMutation( - context, - (workspace) => workspace.featureComplete(args), - (workspace) => workspace.featureCompleteReplay(args), + execute(context, (workspace) => + context.agent === "flow-reviewer" + ? workspace.featureComplete(args) + : workspace.featureCompleteReplay(args), ), }), flow_feature_reset: defineFlowTool({ @@ -337,17 +303,13 @@ export function createTools(options: ToolOptions): FlowTools { "Reset dependents and optionally start one exact next run atomically.", schema: FeatureResetInputSchema, execute: (args, context) => - executeMutation(context, options.validation, (workspace) => - workspace.featureReset(args), - ), + executeMutation(context, (workspace) => workspace.featureReset(args)), }), flow_session_close: defineFlowTool({ description: "Close and archive a session in one convergent operation.", schema: SessionCloseInputSchema, execute: (args, context) => - executeMutation(context, options.validation, (workspace) => - workspace.sessionClose(args), - ), + executeMutation(context, (workspace) => workspace.sessionClose(args)), }), }; } diff --git a/tests/documentation-contract.test.ts b/tests/documentation-contract.test.ts index 662cc1b1..0c8caf12 100644 --- a/tests/documentation-contract.test.ts +++ b/tests/documentation-contract.test.ts @@ -1,6 +1,7 @@ import { describe, expect, test } from "bun:test"; import { access, readdir, readFile } from "node:fs/promises"; import { dirname, join, relative, resolve } from "node:path"; +import { z } from "zod"; import { pinnedBunVersion } from "../evals/bun-toolchain.js"; import packageJson from "../package.json" with { type: "json" }; import { FLOW_CORE_AGENTS, FLOW_CORE_COMMANDS } from "../src/config-shared.js"; @@ -727,29 +728,44 @@ describe("Flow documentation contract", () => { test("pins GitHub Actions Bun to package.json packageManager", async () => { const expected = pinnedBunVersion(packageJson.packageManager); + const Step = z.object({ + uses: z.string().optional(), + with: z.record(z.string(), z.unknown()).optional(), + }); + const Workflow = z.object({ + jobs: z.record(z.string(), z.object({ steps: z.array(Step) })), + }); + const Action = z.object({ runs: z.object({ steps: z.array(Step) }) }); const workflowNames = (await readdir(".github/workflows")) .filter((name) => name.endsWith(".yml")) .sort(); for (const name of workflowNames) { - const text = await readFile(join(".github/workflows", name), "utf8"); - const versions = [ - ...text.matchAll(/^[ \t]*bun-version:[ \t]*(.*)$/gm), - ].map((match) => { - let value = (match[1] ?? "").trim(); - const comment = value.search(/(?:^|\s)#/); - if (comment !== -1) value = value.slice(0, comment).trim(); - if ( - (value.startsWith("'") && value.endsWith("'")) || - (value.startsWith('"') && value.endsWith('"')) - ) { - value = value.slice(1, -1); + const workflow = Workflow.parse( + Bun.YAML.parse(await readFile(join(".github/workflows", name), "utf8")), + ); + const steps = Object.values(workflow.jobs).flatMap((job) => job.steps); + for (const step of [...steps]) { + if (step.uses?.startsWith("./.github/actions/")) { + const action = Action.parse( + Bun.YAML.parse( + await readFile(join(step.uses, "action.yml"), "utf8"), + ), + ); + steps.push(...action.runs.steps); } - return value; - }); - expect(versions.length, name).toBeGreaterThan(0); - expect(versions, name).toEqual( - Array.from({ length: versions.length }, () => expected), + } + const bunSteps = steps.filter((step) => + step.uses?.startsWith("oven-sh/setup-bun@"), ); + expect(bunSteps.length, name).toBeGreaterThan(0); + for (const step of bunSteps) { + if (step.with?.["bun-version-file"] !== undefined) { + expect(step.with["bun-version-file"], name).toBe("package.json"); + expect(step.with["bun-version"], name).toBeUndefined(); + } else { + expect(step.with?.["bun-version"], name).toBe(expected); + } + } } });