From 308533d37c36480231247c8bf282067746b5e8a5 Mon Sep 17 00:00:00 2001 From: matamune Date: Mon, 18 May 2026 00:36:00 +0000 Subject: [PATCH] Add fork maintenance operator runbook --- docs/pages/guides/maintain-a-fork.md | 198 +++++++++++++++++++++++++++ docs/pages/index.md | 1 + docs/tome.config.js | 1 + 3 files changed, 200 insertions(+) create mode 100644 docs/pages/guides/maintain-a-fork.md diff --git a/docs/pages/guides/maintain-a-fork.md b/docs/pages/guides/maintain-a-fork.md new file mode 100644 index 0000000..09c0cfd --- /dev/null +++ b/docs/pages/guides/maintain-a-fork.md @@ -0,0 +1,198 @@ +--- +title: Maintain a fork +description: Operator runbook for dispatching, inspecting, and finishing patch.moi fork maintenance work. +--- + +# Maintain a fork + +Use this runbook when an upstream release or branch movement needs to become a +maintained fork candidate. patch.moi records the event and attempt state. +codex-flows and the selected execution surface do the checkout, rebase, +verification, and optional push. + +The safest default is Actions/local mode with pushes disabled. That does not +require a workspace backend to be running beside patch.moi. + +## 1. Pick the state directory + +Use one durable `DATA_DIR` per patch.moi environment: + +```bash +export DATA_DIR=/var/lib/patch.moi/data +``` + +For a local rehearsal, a temporary directory is fine: + +```bash +export DATA_DIR="$(mktemp -d)" +``` + +patch.moi product state goes under `DATA_DIR`. codex-flows Actions/local run +state goes under `.codex/workspace/actions/flow-client` in the workspace root. + +## 2. Select the execution surface + +For no-backend operation: + +```bash +export CODEX_WORKSPACE_MODE=actions +unset PATCH_WORKSPACE_BACKEND_URL +``` + +For an explicit workspace backend: + +```bash +export PATCH_WORKSPACE_BACKEND_URL=http://127.0.0.1:3586 +export PATCH_WORKSPACE_BACKEND_SECRET=dev-secret +``` + +Do not set both unless you are intentionally testing precedence. A configured +workspace backend URL wins over Actions/local mode. + +## 3. Keep the first run non-pushing + +Leave destructive or externally visible operations off until the candidate is +understood: + +```bash +export CODEX_FLOW_PUSH=0 +export CODEX_FLOW_PUBLISH=0 +``` + +Flow package defaults should also keep pushes and publishing off, but exporting +the flags makes the operator intent explicit. For harness-only local rehearsals +you can also disable network fetches: + +```bash +export CODEX_FLOW_FETCH=0 +``` + +Do not use `CODEX_FLOW_FETCH=0` for a real upstream release unless the runner +already has the release tag and upstream refs. + +## 4. Verify matching before dispatch + +Dry-run the release event. This records nothing and runs no maintenance work: + +```bash +bun run patch.moi -- run codex-release \ + --tag rust-v0.130.0 \ + --dry-run \ + --json +``` + +The output should show the flow steps that will receive the event. For the +current Codex release package, the expected fanout is the bindings update flow +and the fork rebase flow. + +## 5. Dispatch the maintenance attempt + +Dispatch with Actions/local and pushes still disabled: + +```bash +CODEX_WORKSPACE_MODE=actions \ +CODEX_FLOW_PUSH=0 \ +CODEX_FLOW_PUBLISH=0 \ +bun run patch.moi -- run codex-release \ + --tag rust-v0.130.0 \ + --json +``` + +patch.moi writes: + +- `flow-events.jsonl` for the normalized upstream event +- `workspace-dispatches.jsonl` for the dispatch result +- `maintenance-attempts.jsonl` for the attempt record + +codex-flows writes the execution run state under `.codex/workspace/actions`. + +If the dry-run output includes Code Mode steps, enable the Code Mode capability +before dispatching in the runner environment: + +```bash +export CODEX_FLOWS_MODE=code-mode +``` + +The legacy narrow gate `CODEX_FLOWS_ENABLE_CODE_MODE=1` is also accepted. +Without one of those gates, the attempt should block instead of silently +running privileged Code Mode work. + +## 6. Inspect the result + +Start with patch.moi state: + +```bash +bun run patch.moi -- status --json +bun run patch.moi -- attempts --json +bun run patch.moi -- dispatches --json +``` + +Filter to the records that need attention: + +```bash +bun run patch.moi -- attempts --status needs_intervention +bun run patch.moi -- dispatches --status failed +``` + +For Actions/local execution details, inspect the codex-flows state directory: + +```bash +find .codex/workspace/actions/flow-client -maxdepth 2 -type f | sort +``` + +For a workspace backend run, use `sync` after the backend has a terminal run +state: + +```bash +bun run patch.moi -- sync '' --json +``` + +`sync` copies the final status, message, and candidate refs from workspace run +state into patch.moi's maintenance attempt record. + +## 7. Retry or replay when needed + +Retry a transport failure for the same event: + +```bash +bun run patch.moi -- retry '' --json +``` + +Replay an accepted event when the flow package or execution surface changed and +you want a fresh attempt: + +```bash +bun run patch.moi -- replay '' --json +``` + +Retry and replay append new records. They do not mutate old JSONL entries. + +## 8. Enable pushing only after review + +Only enable pushing on a runner that is allowed to update the maintained fork: + +```bash +CODEX_WORKSPACE_MODE=actions \ +CODEX_FLOW_PUSH=1 \ +CODEX_FLOW_PUBLISH=0 \ +bun run patch.moi -- replay '' --json +``` + +Flow packages decide exactly what `CODEX_FLOW_PUSH=1` means. The harness flow +pushes configured branch refs with `--force-with-lease`. The Codex fork flow +pushes the maintained branch and, when configured to publish, release tags. + +Keep `CODEX_FLOW_PUBLISH=0` unless you are intentionally entering the public +release channel. + +## 9. Leave durable state in Git and the forge + +Treat runner checkouts as disposable. The durable outputs are: + +- patch.moi JSONL state under `DATA_DIR` +- candidate branches, tags, pull requests, checks, and artifacts in the forge +- flow run state under the selected codex-flows workspace mode +- release-channel records when a candidate is published or deployed + +If a checkout disappears, patch.moi should still be able to replay the event or +link the attempt to the candidate refs that were already pushed. diff --git a/docs/pages/index.md b/docs/pages/index.md index ecbd03a..372446d 100644 --- a/docs/pages/index.md +++ b/docs/pages/index.md @@ -100,6 +100,7 @@ DATA_DIR=./data FEED_SOURCES_PATH=./feed-sources.json bun run --filter @peezy.te - First harness run: [Run the harness maintenance flow](tutorials/run-harness-maintenance-flow). - Feed intake: [Watch an upstream release](tutorials/watch-upstream-release). +- Operator runbook: [Maintain a fork](guides/maintain-a-fork). - CLI operations: [CLI](reference/cli). - System model: [Architecture](concepts/architecture). - Durable state: [JSONL state](reference/jsonl-state). diff --git a/docs/tome.config.js b/docs/tome.config.js index 9c266ed..ed2ac38 100644 --- a/docs/tome.config.js +++ b/docs/tome.config.js @@ -21,6 +21,7 @@ export default { group: "Guides", pages: [ "guides/run-patch-locally", + "guides/maintain-a-fork", "guides/configure-feed-sources", ], },