@beremaran/ralphie 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,832 @@
+# Changelog
+
+All notable changes to Ralphie are documented here. The project follows
+[Semantic Versioning](https://semver.org/) and the Keep a Changelog structure.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-07
+
+This release replaces the in-process pi agent with headless harness CLIs and
+moves every setting into a configuration file. It contains breaking changes to
+the command line, the configuration, the run state, the JSON Lines output, and
+the way issues are selected and handed back to humans. Read the Removed and
+Changed sections before upgrading.
+
+### Added
+
+- Transient harness failures no longer hand issues off. A rate, usage, session
+  or quota limit, an overloaded or unreachable provider, exhausted credits or an
+  expired login now defers the issue untouched (no labels or comments change),
+  stops the rest of the queue, and exits `75` with a message naming the failure
+  and its reset time. Definite failures still hand off. `scripts/live-smoke.ts`
+  reports such a halt as INCONCLUSIVE and requires a decomposition to have a
+  child worked to a genuine outcome before it passes. It also waits for the
+  created issues to appear in the label listing before it starts Ralphie, passes
+  the implementation scenario only when Ralphie reported the closure and a new
+  commit added `greeting.txt`, and saves each run's `--output json` log to a
+  temp file whose path and `Run completed` line it prints.
+- Parallel reviewer sessions in one working directory no longer collide while
+  skills are injected (`ENOTEMPTY` when setting a same-named repository skill
+  aside). They share one injection, and the last release restores the checkout,
+  including directories Ralphie created.
+- Harnesses and roles. Every agent session runs on a headless harness CLI:
+  Claude Code (`claude`, the default), Codex (`codex`), pi (`pi`) or OpenCode
+  (`opencode`). The `harnesses` (per-harness `model`, `effort`, `approval`) and
+  `roles` keys assign a harness, model and effort to each of the eight roles
+  (`triager`, `preflight`, `implementer`, `fixer`, `standards-reviewer`,
+  `spec-reviewer`, `resolution-verifier`, `decomposer`). Every role falls back
+  to `roles.default`, both reviewers to `roles.reviewer`, and the fixer to the
+  implementer. See `docs/configuration.md`.
+- OpenCode is experimental. Its adapter has not been verified against a live
+  model, so startup refuses any role assigned to `opencode` until the
+  configuration sets `harnesses.opencode.experimental: true`.
+- YAML configuration. Ralphie reads `$XDG_CONFIG_HOME/ralphie/config.yaml` (else
+  `~/.config/ralphie/config.yaml`, or `--config <path>`), validated with a
+  strict schema at startup. Settings layer from defaults, the top level, the
+  matching `repos."owner/repo"` entry, and repeatable `--set path=value`
+  overrides. Review rounds and verification fixes are configurable under
+  `limits`, and `labels` maps the five canonical triage labels.
+- `ralphie init` detects the harnesses on PATH and writes a commented config
+  file at the default location (or `--config`), never overwriting an existing
+  one. A run without a config file points at it.
+- `approval: safe | yolo` (top level, per repository, and per harness) sets how
+  the editing roles run. Startup verifies that every assigned harness is
+  installed, that safe approval is available, and that pi and OpenCode editing
+  roles are set to `yolo`, failing within seconds with the config change that
+  fixes it.
+- `limits.sessionTimeoutMinutes` (`edit` 60, `readOnly` 15) bounds each session;
+  a timeout kills the session's process group. `limits.maxBudgetUsd` caps spend
+  per session, enforced only by Claude Code, with a startup warning for the
+  other harnesses.
+- Vendored skills. Sessions run Matt Pocock's `triage`, `to-tickets`,
+  `implement`, `tdd`, `code-review`, `codebase-design` and `diagnosing-bugs`
+  skills from a pinned copy in `vendor/mattpocock-skills/`, packaged with the
+  release. Ralphie injects them (or `skills.dir`) into the harness's project
+  skills directory for the session, excludes them from Git, removes them
+  afterwards, and generates `docs/agents` tracker and label docs only when the
+  repository lacks them. `bun run skills:sync` refreshes the copy and a
+  scheduled workflow opens a PR when upstream moves.
+- Hand-offs, always on. Anything that needs a human moves the issue to
+  `needs-info` (missing information, conflicting requirements, cannot
+  reproduce, outdated premise; Triage Notes comment) or `ready-for-human`
+  (exhausted implementation attempts or verification repairs, the
+  decomposition depth limit, an external dependency, a decision that needs
+  human judgment; write-up with the diagnostics location). Ralphie replaces
+  the issue's single triage state label, so the next run's intake skips it.
+  Every comment Ralphie posts starts with the AI disclaimer.
+- Opt-in AFK triage (`triage.enabled`, default off). A read-only `triager`
+  session runs the vendored `/triage` over unlabelled issues, `needs-triage`
+  issues and `needs-info` issues the reporter has answered. It promotes an issue
+  to `ready-for-agent` with an Agent Brief (implemented in the same run), hands
+  off to `needs-info` or `ready-for-human`, or closes an already implemented
+  issue as completed once a fresh resolution verifier proves it. It never
+  applies `wontfix` and never writes `.out-of-scope/`.
+- Candidate-commit review gate. After verification Ralphie creates a local
+  candidate commit and runs a standards reviewer and a spec reviewer in
+  parallel over the range diff; smells never block. Approved candidates are
+  squashed into the single delivered commit.
+- Session isolation: sessions start without `GH_TOKEN`, `GITHUB_TOKEN` and the
+  enterprise variants, with an empty `GH_CONFIG_DIR`, origin's push URL
+  disabled inside the workspace, and a fingerprint check that fails any
+  read-only session that changed the checkout.
+- `bun run smoke:live`, an opt-in script that runs the CLI against a scratch
+  repository per installed harness. It is not part of `bun run check` or CI.
+- Harness-neutral session events in JSON Lines output (see Changed) and a
+  shared contract suite for harness adapters.
+
+### Changed
+
+- Breaking: JSON Lines events that reported the `grounding` and
+  `issue-grounding` stages now report `preflight` (pre-flight work) or
+  `hand-off` (hand-off decisions and their verification).
+- Every terminal implementation failure (repeated blocking review findings, a
+  review fix that changes nothing, a failed or timed-out session, a repair that
+  changes the tree after the last review) now ends in an
+  `implementation_exhausted` hand-off, not only an exhausted retry budget.
+- Agent session failures in pre-flight, resolution verification and
+  decomposition now become `ready-for-human` hand-offs too; checkout and GitHub
+  errors still fail so the next run retries.
+- Session isolation also removes `SSH_AUTH_SOCK` and askpass helpers, empties
+  the global and system git config and credential helpers, disables git
+  terminal prompts and makes `GIT_SSH_COMMAND` fail, so a session cannot push
+  over ssh even in yolo mode. Keys readable on disk or in a keyring still need
+  a dedicated OS user.
+- The latest `## Agent Brief` comment is exempt from the 4000-character comment
+  trim and the 20-comment limit when issues are read.
+- `--notify-needs-attention` and `--needs-attention-label` fail with tailored
+  errors; startup now checks each harness against a minimum version and skips
+  the `triager` role when `triage.enabled` is false.
+- Breaking: Ralphie is invoked as `ralphie [owner/]repo` and requires the
+  configuration file; a missing file fails with the path it looked for. A bare
+  repository name takes its owner from `defaultOwner` or the `gh` login.
+- Breaking: intake reads only open issues carrying the `labels.ready-for-agent`
+  label (and every `intake.requireLabels` label). Issues without them are never
+  read, so existing queues must be labelled or run with `triage.enabled`.
+- Breaking: one read-only pre-flight session per issue replaces the grounding
+  session and the 0-5 complexity assessment. It returns `actionable` with
+  `fitsOneSession`, `already_resolved`, `blocked` (skipped without a label
+  change) or `hand_off`. Open-blocker skips from queue order are `skipped`
+  outcomes that change nothing on GitHub. Decomposition no longer carries a
+  complexity estimate.
+- Breaking: hand-offs replace "needs attention" and the notification flags
+  throughout. The outcome kind, result field, progress stage and status, and
+  artifacts are renamed (`hand-off`, `hand_off`, `hand-off-decision`,
+  `pending-hand-off`). The implementer's own result keeps
+  `status: needs_attention`, which is routed as a hand-off request.
+- Breaking: run state is version 15 (version 13 replaced `selection` with the
+  per-role assignments, 14 renamed the hand-off fields, 15 added the `deferred`
+  outcome). Older state is not
+  migrated, and artifacts written by earlier versions (`complexity-decision`,
+  decomposition breakdowns with `body` and `estimatedComplexity`) are not read.
+- Breaking: `--output json` carries `session_event` records instead of
+  `agent_event` records: `{type, sessionID, directory, harness, title?, event}`
+  where `event` is one harness-neutral shape (`session_started`,
+  `assistant_text`, `tool_call`, `tool_result`, `error`, `usage`,
+  `session_finished`). Tool names and inputs are the harness's own. See
+  `docs/operations-and-recovery.md`.
+- Breaking: decomposition runs the vendored `/to-tickets` skill. Children use
+  `{key, title, whatToBuild, acceptanceCriteria, dependsOn}` and are created
+  blockers first in the to-tickets template (`## Parent`, `## What to build`,
+  `## Acceptance criteria`, `## Blocked by`) with the agent-ready label and the
+  parent's `intake.requireLabels` labels. The parent issue's body is never rewritten
+  any more; it is recognised by its native sub-issues, and closed with one
+  disclaimed comment when its children are done.
+- Implementation runs the vendored `/implement` skill, and the implementer
+  writes the commit message (no separate commit-message session). Fixes resume
+  the implementer's session where the harness allows it, starting a fresh
+  session when resuming fails or the estimated context nears 400,000 characters.
+- Read-only sessions have no shell on Claude Code, so Ralphie puts the range
+  diff in the reviewers' prompts.
+- Structured results are validated values, with the optional hand-off request
+  as a field of the result instead of a tool call; repair sessions can no
+  longer raise one.
+- Interactive output: the TUI header no longer shows a model. Pause (`p`), stop
+  (`s`) and quit (`q`) are unchanged.
+
+### Removed
+
+- Breaking: the in-process pi SDK runtime, its credential store and model
+  catalog, and the `@earendil-works/pi-agent-core` and `@earendil-works/pi-ai`
+  dependencies. Ralphie no longer reads `~/.pi/agent/auth.json`,
+  `PI_CODING_AGENT_DIR` or provider API-key variables; each harness CLI keeps
+  its own login. The pi CLI remains available as a harness.
+- Breaking: the TUI model picker (`m`).
+- Breaking: `--branch` (`-b`), `--verify-command`, `--issue-label`,
+  `--issue-sort`, `--implementation-attempts`, `--max-decomposition-depth`,
+  `--workspace`, `--model` and `--thinking`. Each fails with an error naming
+  the configuration key that replaces it (`docs/configuration.md`).
+- Breaking: `--notify-needs-attention`, `--needs-attention-label` and the
+  `notifications` configuration section. Hand-offs are always on, so there is
+  nothing left to opt into; each flag fails with a tailored error (see
+  Changed).
+
+## Before the harness release
+
+Everything below predates the harness release. It was kept under a single
+Unreleased heading, so it mixes what shipped in v0.1.0 to v0.1.2 with changes
+merged afterwards and is not attributed to a version. Mentions of removed
+surfaces (OpenCode, the pi SDK, `--on-needs-attention`, `lgtm`, and so on)
+describe history, not the current tool.
+
+### Removed
+
+- Remove the `quiet` and `verbose` output modes. `--output` now accepts only
+  `default` (live transcript and progress) and `json` (JSON Lines). The
+  structured `details` payload is no longer rendered on human-readable lines;
+  JSON output and the `events.jsonl` audit retain it.
+
+- Remove `--max-issues`, `--implementation-fallback-model`, `--resume`,
+  `--dry-run`, and `--clean`. Every run now processes the whole matching open
+  issue queue with no budget, retries always use the selected model, and there
+  is no preview or resume path. The workspace is removed before preparation
+  and after a successful run; cleanup is skipped when the run fails, drains
+  with issue failures, or is cancelled. Notification recovery, state loading,
+  legacy-state migration, and the read-only dry-run executor and planner are
+  gone. `RunState` is version 12.
+
+- Remove the halt policies. `--on-needs-attention` and `--on-issue-failure` are
+  gone; a needs-attention outcome or an ordinary issue failure now always
+  records the outcome, leaves the issue open, and continues the queue. A
+  drained run exits `1` when any issue failed, and the former handled-stop exit
+  status `2` no longer exists.
+
+- Remove dead integration weight inherited from the removed modes: managed
+  feature-branch revision safety, the feature-branch and base-restore Git
+  operations, the always-false `allowMissingRemoteBranch` seam, unused safety
+  exports, and progress rendering for events pi never emits (compaction,
+  automatic/summarization retries, queue/session/entry updates, thinking-level
+  changes, and bash execution updates). No behavior change.
+
+- Remove the `pr` workflow. Ralphie now always delivers through the direct
+  `lgtm` path: the `--workflow` flag, feature branches, pull requests, the
+  post-PR review/revision coordinator, the check gate, and the read-only check
+  observer are gone, along with their Git, run-state, artifact, prompt, test,
+  and documentation surfaces. `RunState` is version 10.
+
+- Remove every top-level execution mode other than the issue workflow. The
+  `--mode` flag, `maintain-issues`, `get-pipelines-green`, and
+  `--duplicate-action`/`--max-attempts`/`--pipeline-timeout` are gone, along
+  with the maintenance snapshot/planning/state subsystem, the pipeline
+  delivery/diagnostics/repair subsystem, and their tests and docs.
+
+- Replace the external OpenCode server integration and the multi-harness/ACP
+  discovery layer with an in-process agent runtime (itself replaced by the
+  harness CLIs, see above). Deleted
+  `src/harness/` (six-kind harness contracts and Antigravity
+  executable/ACP discovery) and `src/opencode/` (server client, transport,
+  permission watcher, and model-variant catalog). `--opencode-url`,
+  `--opencode-token`, `OPENCODE_URL`, `OPENCODE_TOKEN`, and the mandatory
+  Antigravity preflight are gone; no external agent server is required.
+
+- Remove every non-npm distribution channel: the native standalone bundles
+  (four-platform `bun compile` builds, `scripts/install.sh`, `bun run targets`
+  catalog machinery), the Homebrew tap/formula (generators, validators,
+  reconciliation, checksums), the Docker image and container registry
+  publication (GHCR, OCI indexes, tag plans, SBOM/SLSA attestations), and the
+  release checksum/Sigstore verification surface (`SHA256SUMS`). The release
+  and public-distribution workflows are replaced by one tag-triggered publish
+  workflow (`.github/workflows/npm-publish.yml`): validate the tag/package
+  version (`scripts/validate-npm-context.ts`), build the package bundle,
+  smoke-check the packed tarball, and `bun publish`. `bunx
+  @beremaran/ralphie` is the only supported way to run Ralphie.
+
+- Remove the shared redaction implementation (`src/shared/redaction.ts`,
+  `tests/shared/redaction.test.ts`) and every `[REDACTED]` reporting assertion.
+  `redactSensitiveText`/`redactSensitiveValue` no longer exist; the terminal
+  control sanitizer they contained moved to `src/shared/terminal.ts`
+  (`stripTerminalControls`).
+
+### Changed
+
+- Replace the hand-rolled interactive renderer with OpenTUI, the same
+  terminal rendering core OpenCode 1.0 uses. Interactive runs now render a
+  borderless layout: a background header line with the repository, active
+  model, and pause state; an issue sidebar with outcome glyphs and a
+  processed count; a per-issue streaming transcript with role bullets,
+  indented assistant text, dim thinking, and one-row tool calls with elapsed
+  time; and a footer status line. The sidebar lists the discovered queue
+  with each issue's outcome and follows the active issue until the user
+  navigates; `[`/`]` (or Ctrl+Left/Right) switch between processed, active, and
+  queued issues. Interactive runs start paused so the discovered plan can be
+  inspected before work begins; `p` resumes or pauses the queue between issues,
+  `s` stops the queue after the active issue and drains the run with a "Run
+  stopped by request" summary, and `q` cancels immediately. The
+  footer/breadcrumb/terminal-controller stack and its PTY test suites are gone. Plain (piped/CI) and JSON output are unchanged in
+  shape, and the interactive renderer loads lazily so help, plain, and JSON
+  paths never touch the native module.
+
+- Report the discovered issue queue and skipped issues through progress:
+  `issue-queue` events carry the pending issue numbers and titles, and an issue
+  that no longer matches the filters is reported as skipped instead of
+  disappearing silently. Plain output gains one line per skipped issue and the
+  JSON audit gains the queue details.
+
+- Give GitHub adapters an owned session. `connect()` authenticates once and
+  the capability adapters read the client internally, so no port method,
+  executor context, or workflow call carries an Octokit handle; the SDK is
+  confined to `src/github/adapters/`.
+
+- Inject `Clock`, `IdGenerator`, and `RunLayout` through the runtime bundle.
+  Workflow, artifacts, and recovery no longer call `new Date()`,
+  `randomUUID()`, or compose workspace paths; the composition root resolves
+  the workspace expansion and run layout.
+
+- Move parent completion and issue preparation into `issues/app/` with their
+  contracts in `issues/ports.ts`, and add the `IssueWorkflow` driving port so
+  the CLI depends on the use-case contract rather than the workflow function.
+
+- Add shared port contract suites under `tests/contracts/` that run the same
+  behavioral spec against in-memory fakes and the live adapters for
+  `RunEventLog` and `IssueArtifactStore`.
+
+- Restructure the source into hexagonal, context-first packages: each bounded
+  context (`agent`, `pi`, `github`, `git`, `issues`, `progress`, `run`,
+  `process`, `workspace`, `workflow`) owns its `ports.ts` contract, its domain
+  model, and its `adapters/` implementation together. `src/runtime.ts` and
+  `src/command.ts` are the only modules that instantiate adapters. Non-adapter
+  code imports no `node:fs`, `node:child_process`, vendor SDK, or process
+  stream; Octokit appears only inside the `github` context; the artifact and
+  recovery file systems are injected ports implemented under
+  `src/issues/adapters/`. `tests/architecture.test.ts` enforces these rules.
+
+- Decouple execution from presentation. The progress contract now lives in
+  `src/ports/progress.ts` (no rendering or I/O dependencies), the renderers in
+  `src/progress/` implement it, and execution code no longer imports the
+  presentation layer. The `events.jsonl` audit moved out of the renderer into
+  `src/run/event-log.ts` and is closed by the run before workspace removal; the
+  dead `writeRaw`/`stopPersisting` surface is gone. `tests/architecture.test.ts`
+  enforces the import directions and process-stream ownership.
+
+- Verification is now opt-in. The `package.json` `bun run check` discovery
+  default is removed; when no `--verify-command` is supplied the deterministic
+  gate is skipped and review proceeds on the staged diff. Supplied commands
+  still run through `/bin/sh`, their evidence is still bound to the staged
+  tree, and non-zero exits still trigger the bounded repair loop.
+
+- Collapse every per-stage thinking setting into one `--thinking` level applied
+  to all sessions. The `--grounding-thinking`, `--implementation-thinking`,
+  `--complexity-thinking`, `--review-thinking`, and `--commit-thinking` flags
+  are gone; the default level remains `medium`.
+
+- Pi is now the only execution backend. `--model provider/model` resolves
+  against pi's built-in catalog (defaulting to the model saved in pi's
+  `settings.json`), thinking flags accept pi levels (`off` through `max`), and
+  credentials resolve through `~/.pi/agent/auth.json`
+  (`PI_CODING_AGENT_DIR`) with provider environment variables as fallback.
+- Agent tools are pi's built-in `read`, `write`, `edit`, and `bash`, rooted at
+  the repository checkout and guarded before execution (delivery-state shell
+  denylist plus workspace path containment); review-profile sessions expose
+  read-only tools. JSON transcript records are now `agent_event`, and the
+  progress stage `opencode-runtime` is `agent-runtime`.
+- Add `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, and
+  `proper-lockfile` as runtime dependencies; pi packages stay external to the
+  bundle so their lazy provider SDKs install through npm.
+
+- Complete the post-PR review and revision lifecycle. `pr` delivery now
+  persists the immutable pull-request base/head, runs a resumable coordinator
+  with one shared five-attempt review budget, performs fresh exact-tree
+  non-force revisions when findings require changes, publishes head-scoped
+  review attempts idempotently, and records review/revision/publication/check/
+  merge boundaries in RunState v9 and the per-issue delivery artifact.
+  Merging requires a fail-closed proof containing approved structured review
+  evidence and a stable green check snapshot for the same PR/base/head; stale
+  or incomplete proof cannot merge. Exhaustion and recoverable delivery
+  failures retain the open issue, branch, and PR. Added service, coordinator,
+  workflow, resume, failure-boundary, and end-to-end coverage plus the
+  lifecycle/recovery documentation.
+
+- Complete the first user-visible `--mode maintain-issues` release slice. The
+  mode is a bounded one-shot issue-reconciliation pass separate from the
+  default `--mode issues` delivery queue: read-only OpenCode planning feeds
+  schema/policy validation, while deterministic GitHub services perform only
+  live-revalidated additive labels, managed questions/answers, and reciprocal
+  relationship or duplicate links. Duplicate closure remains an explicit
+  `--duplicate-action close` opt-in with link → existing `duplicate` label →
+  duplicate-close ordering; uncertainty, stale data, and insufficient evidence
+  skip or replan instead of guessing. Versioned maintenance state checkpoints
+  every action for exact resume, and maintenance dry runs perform no workspace,
+  GitHub, state-file, artifact, or event-log mutation. Added offline
+  fake-GitHub/OpenCode integration coverage for reconciliation, ambiguity,
+  interruption/resume, output modes, permissions, dry-run isolation, and exit
+  codes (`tests/integration/maintain-issues.test.ts`). The documentation records
+  the required permissions, output/recovery contract, and first-release
+  non-goals; no mutation-enabled network smoke test is included.
+
+- Dependency-blocked issues (open queue prerequisites) are recorded as
+  needs-attention outcomes but no longer publish a needs-attention GitHub
+  comment or label: the opt-in notifier is reserved for agent-reported
+  blockers that need a human decision, while queue-order blocks resolve by
+  completing the open dependencies. The `--on-needs-attention` halt/continue
+  policy and run-level progress events are unchanged.
+
+- Progress detail, activity rows, and short JSON snapshots are no longer
+  redacted. The reporting boundary now preserves supplied values verbatim
+  (`src/progress/activity.ts` sanitizes only terminal control sequences),
+  matching the already-lossless `opencode_event` transcript records and
+  durable event log. Credentials and other sensitive values pass through into
+  transcripts, breadcrumbs, JSON Lines, and `events.jsonl` exactly as
+  supplied; only terminal control sequences are stripped from human-readable
+  rows. Documentation (`README.md`, `docs/architecture.md`, and
+  `docs/operations-and-recovery.md`) now describes this intentional unredacted
+  output contract.
+
+- Validate OpenCode model/variant compatibility before execution and fail fast
+  on silent turns. After the OpenCode runtime starts, the workflow lists the
+  server's model catalog (`src/opencode/server.ts`, `src/opencode/variants.ts`)
+  and checks every planned stage variant (grounding, complexity,
+  implementation, review, commit message, plus the implementation fallback
+  model) against the variants each model advertises (`default` is always
+  accepted). Unsupported combinations abort the run before any issue work with
+  the offending stage, model, available variants, and the exact
+  `--*-thinking` flag to adjust, instead of failing mid-run with a misleading
+  contract error. Separately, structured and unstructured prompts now treat a
+  turn that produces no assistant message (for example a server-side model
+  resolution failure) as a distinct silent-turn failure naming the model,
+  variant, and session, with no pointless contract-violation retries; genuine
+  contract misses now emit the transcript and include a response preview in
+  the error. Covered by `tests/opencode-variants.test.ts`, new silent-turn
+  cases in `tests/opencode-client.test.ts`, and fail-fast workflow tests.
+
+- Lock down the cross-mode display contract with end-to-end regression
+  coverage: the interactive in-progress activity surface is measured in
+  physical terminal rows (never newline counts) and stays within the shared
+  three-row replaceable region across repeated tool calls, long
+  commands/paths, narrow terminals and resize, interleaved streamed assistant
+  text, ANSI/control-sequence boundaries, completion, failure, and cleanup;
+  streamed assistant text is preserved exactly, plain/CI output stays
+  deterministic and append-only with no carriage-return or ANSI cursor bytes,
+  JSON Lines output remains parseable and lossless, and quiet mode surfaces
+  no routine activity. The command-runtime display suite drives the real
+  coordinator wiring through `runCommand`, and the docs describe the bounded
+  interactive region, concise completion/error summaries, and the
+  noninteractive fallback.
+
+- Route the OpenCode event stream and progress updates through the compact activity
+  surface in the real coordinator/CLI path: tool-call start/delta/end, tool
+  execution start/update/end, bash execution updates, streamed thinking,
+  compaction/retry lifecycle, and active progress changes map to bounded
+  activity rows in the replaceable interactive region. The human transcript no
+  longer streams multi-line partial/final tool output or streamed thinking;
+  each tool completion emits at most one concise `✓ <tool> done` line, and a
+  failure emits one sanitized, 140-character-bounded line with enough error
+  detail to act. Assistant text deltas, session headers, durable breadcrumbs,
+  and lossless JSON `opencode_event` records are unchanged, the region never clears
+  or corrupts assistant response bytes, and `--output verbose` keeps the live
+  row count at its fixed three-row cap. Plain, JSON, and quiet modes retain
+  their append-only/structured/failure-only contracts. Coordinator-level tests
+  cover repeated calls, missing ids, interleaved assistant text, success and
+  failure, and mode-specific behavior.
+
+- Render the interactive activity view in one replaceable three-row terminal
+  region: the sticky stage/status line plus the bounded activity rows share a
+  single region whose total height never exceeds three terminal rows (no panel
+  added beneath the footer), every row is clipped before it can wrap, and each
+  replacement repaints the region in place using the terminal stream boundary
+  primitives: repaints are deferred while a transcript fragment is open
+  mid-line or a control sequence is incomplete, and the region clears/restores
+  without overwriting streamed assistant text, splitting an ANSI/control
+  sequence, or inserting bytes into a partial line. Resize, disposal, stale
+  rows, and completion removal are handled; cursor controls remain limited to
+  interactive mode, and plain, CI, piped, JSON, and quiet surfaces stay
+  append-only or structured with no cursor-control artifacts.
+
+- Finalize the interactive footer layout as `durable-transcript-breadcrumbs`
+  (`INTERACTIVE_FOOTER_LAYOUT_STRATEGY`, `INTERACTIVE_FOOTER_USES_SCROLL_REGION=false`,
+  `INTERACTIVE_FOOTER_USES_RESERVED_ROW=false`): the status is an in-place
+  replaceable region below streamed content, never a reserved bottom row or
+  DECSTBM scroll region, so reserved-row/scroll-region cursor manipulation is
+  disabled (no DECSTBM, CUP, alternate-screen, or save/restore sequences; only
+  in-place erase and single-row step-up repaint the region with strict
+  clear-before-draw). Interactive mode requires stdin and stderr TTYs with `CI`
+  neither `"true"` nor `"1"`; footer-only repaints coalesce at roughly 100–125 ms
+  while transcript token deltas stream immediately; partial-line/control-open
+  fragments defer repaints, rows clip at their paint-time width, resize repaints
+  only at a safe boundary, and completion/interruption (SIGINT/Ctrl-C)/failure
+  erases the region, settles on a fresh line, and emits no further bytes.
+  Plain/CI output is deterministic append-only with no `ESC`/carriage-return or
+  footer residue, verbose never expands the three-row cap, quiet keeps failures
+  and handled needs-attention stops only, and JSON stays JSON Lines on stdout
+  with stderr empty. `README.md` and `docs/operations-and-recovery.md` now
+  publish exactly this tested contract,
+  locked by `tests/progress/interactive-footer-layout-strategy.test.ts`, the PTY
+  streaming-stress fixture, the real-PTY lifecycle fixture, and the
+  noninteractive cleanup matrix.
+
+- Deliver managed feature-branch revisions as one deterministic operation
+  with authoritative remote reconciliation: the revision safety checks run
+  before staging/commit and again immediately before the push, the exact-tree
+  revision commit is created from the allowed staged tree, the push uses only
+  Git's non-force mode to the explicit `HEAD:refs/heads/<branch>` destination
+  ref, and the outcome is classified from the authoritative post-push
+  `git ls-remote` read (never from a tracking ref or command response alone).
+  The discriminated, typed outcome distinguishes `confirmed` delivery (remote
+  equals the new commit with a clean checkout, including a lost push response
+  reconciled to success), `external-movement` (remote no longer equals the
+  expected prior head: halt without retry or force), and `ambiguous` delivery
+  (remote read cannot prove whether the new commit arrived; the created clean
+  commit is retained for safe reconciliation). Movement detected before
+  staging/commit prevents the commit from being created, cancellation is
+  checked at every mutation boundary, the push is attempted at most once, and
+  the `lgtm` direct-push path and its shared, regression-tested helpers are
+  unchanged.
+
+- Tighten human transcript bounds to 3 lines/140 characters: tool incremental
+  output uses `LIVE_OUTPUT_LIMIT=140`, thinking/assistant streams use the same
+  140-character bound, and final previews truncate to 3 lines/140 characters
+  with the existing truncation marker. Truncated tool, thinking, and assistant
+  streams still report background totals (total characters and lines with a
+  `truncated` marker). JSON and durable logs remain lossless.
+
+- Add the needs-attention recovery contract across the OpenCode boundary, issue
+  executor, recovery service, and local end-to-end path: bounded fenced
+  `needs-attention` blocks (`reason` one of `outdated_premise`,
+  `conflicting_requirements`, `missing_information`, `external_dependency`, or
+  `cannot_reproduce`, plus an optional message capped at 2,000 characters)
+  accompany the required schema-valid fenced `json` result from grounding,
+  complexity, implementation, review-fix, commit-message, review, and
+  decomposition sessions; each signal is confirmed by exactly one fresh
+  read-only verifier session before any further artifact, Git, or GitHub
+  mutation. A confirmed `needs_attention` disposition persists the structured
+  decision with its summary, evidence, questions, and issue-freshness
+  fingerprint, leaves the source issue open, performs no GitHub mutation and
+  no commit or push, and restores the clean checkpoint by removing staged,
+  unstaged, and untracked agent changes; verifier rejection continues the
+  original attempt, and diagnostic, restoration, or repository-invariant
+  failures are reported as recoverable rather than successful. Recovery
+  diagnostics live under
+  `runs/<run-id>/issues/<issue-number>/needs-attention-<id>/` with
+  `changes.patch` and `metadata.json`, keyed by fingerprint and reused only on
+  exact matches.
+
+- Bound every command execution with a hard deadline so a hung process cannot
+  stall an unattended issue run: OpenCode task shell commands default to a
+  120-second timeout with a 600-second maximum (an omitted `timeout` gets the
+  default and a larger declared timeout is clamped), Ralphie-owned git/gh and
+  workspace commands default to a 10-minute timeout via `CommandRunnerLive`,
+  and deterministic verification commands run under a 30-minute timeout. A
+  timed-out command is killed and reported as `CommandTimeoutError` with the
+  deadline and command in the message; agent tool calls surface
+  `Command timed out after N seconds` with partial output and can retry with
+  an explicit timeout.
+
+- Resolve open dependencies on decomposed tracking parents transitively to
+  their open leaf children in the issue queue, so a child depending on a
+  decomposed-but-open container issue can never deadlock against a parent
+  that is never queued for execution.
+- Surface dependency-blocked end-of-run issues as explicit needs-attention
+  outcomes (reason `external_dependency`) with evidence naming each open
+  dependency, instead of failing the run with a bare "blocked by open
+  dependencies" error: `--on-needs-attention halt` stops with the handled
+  stop; `continue` completes the run with the preserved issues still pending,
+  and no GitHub notification or label is published for queue-order blocks
+  (the opt-in notifier is reserved for agent-reported blockers).
+- Pin grounding and resolution-verification evidence to the exact
+  checked-out commit: the read-only prompts now name the checked-out SHA
+  alongside the repository path and target branch.
+
+### Fixed
+- Live OpenCode transcript streaming renders every `thinking_delta` / `text_delta`
+  (and tool output update) inline on the already-open `⋯ thinking` / `✦ assistant`
+  row instead of forcing one token per `│`-prefixed line; incremental deltas no
+  longer break the open stream, so interactive output wraps naturally at the
+  terminal width and durable progress/breadcrumb lines still interleave cleanly.
+- Repeated structured-output attempts that never produce a schema-valid result
+  now trip a circuit breaker that aborts the OpenCode session after five
+  consecutive failures and reports the likely cause instead of letting the
+  model retry until the prompt-attempt budget expires.
+### Changed
+
+- Added `--max-decomposition-depth` (default `3`) and persisted it in run state.
+  A direct or review-escalated decomposition beyond the configured ceiling now
+  leaves the issue open as `decomposition_limit_reached` needs attention and
+  continues independent queued work instead of failing and halting the run;
+  dependent issues remain blocked.
+
+- OpenCode implementation sessions now allow ordinary composed shell commands,
+  pipes, redirection, and interpreters while continuing to reject explicit
+  orchestration-owned Git/GitHub mutations.
+- Implementation completion is schema validated. Unresolved empty diffs enter
+  a bounded fresh-session retry loop with verifier evidence, configurable
+  implementation thinking, retry count, and optional fallback model.
+- A tentative `already_resolved` grounding route now continues through
+  complexity assessment when fresh verification finds unresolved work. The
+  verifier evidence seeds the first implementation session, unresolved
+  resolution artifacts cannot short-circuit resumed work, and operational or
+  malformed verification failures still fail closed.
+- `--on-issue-failure continue` restores failed issue checkouts and drains
+  independent queued work before returning an aggregate non-zero result;
+  failed prerequisites continue to block dependent issues.
+
+- Deterministic verification command failures now enter a bounded repair loop
+  instead of immediately failing the issue and halting the queue. Each repair
+  receives the exact staged diff and bounded failed-command evidence in a fresh
+  mutating session, is restaged and reverified, and must pass before review or
+  commit. Repairs that change an approved staged tree force another review;
+  exhausted repairs and verification integrity faults still fail closed.
+
+- Decomposition now uses native GitHub sub-issues and dependencies: every
+  created or recovered child is attached to the original issue as a native
+  sub-issue, declared `dependsOn` edges become native `blocked_by`
+  relationships, and the decomposed parent stays open as a tracking issue
+  instead of being closed as a duplicate. Child bodies keep only the stable
+  recovery marker and dependency list, and decomposed parents are never
+  re-queued for execution. Native relationships are reconciled idempotently on
+  resume; conflicting hierarchy or markers halt with a recovery diagnostic.
+- Dequeued issues are refreshed from GitHub before branch or OpenCode work; closed or
+  label-ineligible issues are durably skipped without mutations, and cached
+  grounding, complexity, and resolution decisions now require matching live
+  issue freshness metadata.
+- The `pr` workflow now gates merged delivery: after creating or finding the
+  matching feature-branch pull request it persists the PR number and head SHA,
+  publishes review attempts, waits for the exact-SHA check observer to reach
+  its documented green state, re-reads the PR immediately before merging, and
+  invokes the expected-head merge only while the head is unchanged. A failed,
+  cancelled, timed-out, absent, unknown, changed-head, closed, or unmergeable
+  gate retains the feature branch and PR, persists an active recoverable
+  closure gate, and never merges or closes the source issue; resume locates
+  the existing PR instead of duplicating it, continues polling pending gates,
+  invalidates saved green evidence on a changed head, re-observes failed
+  gates on a later rerun, and reconciles an already-merged PR without another
+  merge call. Run state version 6 records the PR number, observed head SHA,
+  latest normalized check snapshot, observation start/last-update timestamps,
+  gate status, and terminal reason for an active PR closure, with migration
+  coverage for versions 2–5. The `lgtm` workflow and dry-run paths are
+  unchanged, and GitHub mutations remain in the deterministic `src/github/`
+  services.
+
+### Added
+
+- `bun run probe:structured-output` accepts `--union` to pre-flight a model
+  against the exact grounding decision contract plus `--model provider/model`,
+  `--agent`, and `--variant` for targeting a specific model before a run.
+- The `pr` gate now streams dedicated `pr-gate` progress events for
+  registration (pull-request number and exact head SHA), poll progress only
+  for meaningful check transitions (registration, checks registering,
+  appearing or disappearing, and status changes: unchanged polls never
+  emit), head invalidation, and terminal success/failure, timeout, and
+  cancellation with the check summary and reason. Human and verbose output
+  explain the PR number, exact SHA, check summary, and reason; JSON output
+  exposes the structured normalized snapshot and timestamps; quiet output
+  suppresses the routine gate milestones while still reporting gate failures.
+  The observer exposes an optional `onTransition` callback invoked only on
+  meaningful transitions, and a merged gate record now retains the green
+  observation snapshot as persistent merge evidence.
+- Deterministic PR-gate regression coverage: a local end-to-end PR workflow
+  with a fake GitHub check service that records merge calls and proves none
+  occur before a stable green snapshot, resume from pending/green/failed and
+  already-merged gate states, unknown and cancelled gate outcomes, expected-head
+  merge rejection recording a stale gate, pending-to-failure and mixed Check
+  Run/commit-status transitions, and quiet/JSON rendering of gate events.
+
+- A deterministic, read-only pipeline observation service
+  (`src/github/pipeline-observation.ts`) that polls normalized pipeline
+  snapshots for one exact SHA: it tolerates an initial registration grace
+  period while no checks are visible, keeps polling while any item is pending,
+  requires configurable stable terminal confirmations, fails closed on
+  unknown, cancelled, failing, and empty terminal results, collects every
+  page from Check Runs and legacy commit statuses, uses bounded exponential
+  backoff and bounded rate-limit retries with delta-seconds, HTTP-date, and
+  reset metadata without retrying before server hints or sleeping past an
+  absolute deadline, honors caller cancellation reasons, emits only
+  meaningful state transitions, and finishes with a race-safe remote-HEAD
+  check that reports a stale result when the branch advances so callers can
+  follow a newly advanced HEAD.
+- Complete the `--mode get-pipelines-green` release slice. The dedicated
+  direct base-branch runner authenticates and prepares one selected branch,
+  observes every supported Check Run, Check Suite, legacy status, and Actions
+  workflow source for one exact SHA, collects bounded terminal-sanitized
+  diagnostics, and runs a persisted repair/verify/commit/non-force-push loop.
+  A green exit requires a non-empty all-passing snapshot with no source or
+  completeness errors and a final current-HEAD proof; pending, acceptable,
+  failing, cancelled, unknown, and no-pipeline outcomes fail closed. The
+  versioned pipeline state adapter records absolute deadlines, confirmed-push
+  attempts, checkpoints, fingerprints, diagnostic references, and commit
+  evidence atomically; resume invalidates stale snapshots, reconciles an
+  ambiguous push without duplicate charging, and preserves the original
+  deadline. Dry-run performs authentication, preparation, observation, and
+  diagnostics only. The CLI reference, end-to-end trace, safety model,
+  operations/recovery guide, architecture map, and README document the mode,
+  output/exit contract, incompatible flags, provider limitations, untrusted CI
+  handling, artifact paths, cancellation, and recovery behavior.
+- An opt-in `RALPHIE_RUN_GITHUB_SUB_ISSUES_SMOKE` integration test that
+  exercises the real native sub-issue and dependency API in a configured
+  sandbox repository: attachment and dependency idempotency, reads, live
+  parent-completion reconciliation, and cleanup.
+- Deterministic decomposed-parent completion: finishing the final child
+  reconciles its tracking parent immediately, and every non-dry-run run
+  reconciles discovered decomposed parents, closing a parent as `completed`
+  only when every native sub-issue is closed. Parents awaiting sub-issue
+  attachment recovery, non-Ralphie parents, and already-closed parents are
+  left untouched.
+- Dry-run decomposition reporting: a complexity 4–5 dry run performs the
+  read-only breakdown session and reports the intended native sub-issue
+  hierarchy: children to create or reuse, sub-issue attachments, dependency
+  edges, and the open tracking parent: without mutating GitHub or writing
+  artifacts. An unverified needs-attention signal from the planning session is
+  reported as a needs-attention route without invoking recovery.
+- A deterministic GitHub issue-relationship domain service
+  (`src/github/issue-relationships.ts`) that lists, attaches, and validates
+  native sub-issues and dependencies with idempotent, response-loss-safe
+  mutations and actionable unsupported-endpoint errors.
+- A terminal output controller (`src/progress/terminal-controller.ts`) that
+  wraps the footer view scheduler and the shared `ProgressOutput` primitives
+  and arbitrates every transcript/raw write with the terminal stream boundary
+  tracker: an active footer is cleared before transcript or durable progress
+  output, token deltas are forwarded immediately, and the footer is restored
+  only at safe line boundaries. Durable progress lines are deferred while a
+  transcript fragment is open mid-line so progress never merges with,
+  overwrites, or falsely closes the fragment; footer bytes are emitted only
+  through the strategy's footer surface and never enter transcript/control
+  payload or durable scrollback; every replacement repaint clears a visible
+  footer before drawing the new one; durable transcript breadcrumbs remain
+  the safe default fallback with cursor-reserved-row behavior disabled by
+  default. Coverage exercises partial transcript lines, progress
+  interleaving, immediate token forwarding, split ANSI/control strings,
+  footer suppression while unsafe, restoration after a safe boundary, and
+  strict clear-before-draw ordering through fake sinks and fake strategies.
+- A persisted `created-issue-dependencies` artifact that records each child's
+  dependency issue numbers so queue eligibility never depends on live GitHub
+  state alone.
+
+- A single package-version authority with build-time commit metadata and plain
+  or JSON `--version` output that works without repository or OpenCode configuration.
+- An isolated package smoke check that inspects the tarball allowlist, installs
+  production dependencies in a fresh project, and verifies scoped identity and
+  manifest-backed `--version` output.
+- Staged-tree-bound deterministic verification before review, after review
+  fixes, and before commit, with persisted command evidence and repeatable
+  `--verify-command` overrides.
+- Stage-specific thinking controls for grounding, complexity routing, review,
+  and commit-message generation.
+- Discriminated top-level CLI configuration for issue,
+  `maintain-issues`, and `get-pipelines-green` modes, including duplicate
+  handling policy, bounded attempts, and strict pipeline timeout values.
+- Read-only issue grounding with a persisted needs-attention deferral: blocked
+  issues keep their evidence, questions, and freshness fingerprint, remain
+  open, and are never closed or marked complete; complexity is never a
+  needs-attention reason.
+- An explicit `halt` (default) / `continue` needs-attention policy with
+  versioned run-state migration, resume conflict protection, exit status `2`
+  for handled stops and exit `0` only when `continue` drains the queue.
+- Confirmed needs-attention recovery that atomically preserves bounded,
+  binary-safe worktree diagnostics before restoring and verifying the exact
+  clean issue checkpoint.
+- Resumable needs-attention handoffs with one fresh read-only verifier for every
+  executor signal, immutable confirmation before recovery, and idempotent,
+  freshness-bound diagnostics across interruptions.
+- Durable needs-attention notification recovery: structured outcomes and label
+  intent are saved before GitHub mutation, and resume retries the stable marker
+  without rerunning agent work.
+- An explicit, disabled-by-default `--notify-needs-attention` CLI opt-in with a
+  trimmed `--needs-attention-label`; label-only usage is rejected, dry runs
+  never notify, and failed notifications retain their intent for safe resume
+  and retry.
+- Native Bun CLI foundation with GitHub, Git, workspace, and OpenCode domain
+  services.
+- Resumable issue execution with complexity routing, bounded review loops,
+  deterministic commits and pushes, and dependency-aware decomposition.
+- Typed progress events, JSON Lines output, and diagnostics.
+- Structured no-change resolution verification with persisted evidence.
+
+### Changed
+
+- Refresh each issue before mandatory grounding, route actionable work through
+  the existing complexity thresholds, require fresh concrete verification for
+  already-resolved closure, and keep needs-attention outcomes out of closure
+  and PR delivery. Complexity is never a needs-attention reason.
+- Document the cross-mode display contract: interactive sticky footer and
+  contextual OpenCode session output, periodic and lifecycle breadcrumbs, the
+  `LIVE_OUTPUT_LIMIT` character threshold and human-preview defaults, active
+  leaf-stage status, append-only plain/CI output, quiet output limited to
+  failures and handled needs-attention stops,
+  lossless JSON Lines without human breadcrumb records, and the independent
+  durable progress-event log preserving supplied values (never redacted).
+- Expose grounding and needs-attention decisions consistently across default,
+  interactive, verbose, quiet, and JSON Lines output, including complete
+  evidence, questions, artifact paths, policy, and final outcome counts.
+- Make dry-run grounding and routing strictly read-only: report all routes,
+  reuse persisted decisions without rewriting issue artifacts, and keep resumed
+  dry runs away from implementation, delivery, and Git/GitHub mutations.
+- Refresh live issue and comment metadata when resuming pending work, and reuse
+  needs-attention grounding only while its freshness fingerprint matches;
+  changed or invalid artifacts are atomically invalidated before regrounding.
+- Keep OpenCode configuration separate from persistent workspace state:
+  `--opencode-url`/`OPENCODE_URL` and `--opencode-token`/`OPENCODE_TOKEN` are
+  operator-owned inputs, while local background-service discovery remains
+  outside the workspace state tree.
+- Define noninteractive `github.com` authentication through the preferred
+  `GH_TOKEN` and fallback `GITHUB_TOKEN` environment variables, without
+  requiring `gh auth login` or a mounted GitHub CLI profile.
+- Document the published scoped Bun package and use
+  `bunx @beremaran/ralphie` for installation, version verification, dry-run,
+  and workflow examples; the scope distinguishes this CLI from the unrelated
+  unscoped npm package named `ralphie`.
+- Resolve dependencies on decomposed closed issues to their open descendants,
+  stop repeated identical review findings early, permit safe compound shell
+  inspection commands, and use GitHub REST API version `2026-03-10`.
+- Polish human-readable OpenCode streaming with grouped session blocks, readable tool
+  calls, indented de-duplicated tool output, bounded previews, and safe handling
+  of terminal control sequences while preserving the lossless JSON event stream.
+- Stream the complete OpenCode event transcript, including token-level thinking
+  and assistant output plus tool calls and results, and remove parallel issue
+  and OpenCode session execution.
+- Consolidate the CLI surface: fold `--issue-order` into
+  `--issue-sort <field>[:asc|desc]`; use `--thinking` for the selected OpenCode
+  variant and `--opencode-url`/`--opencode-token` for the external server;
+  replace `--start-clean` and `--cleanup` with `--clean <start|end|both>`;
+  and replace `--verbose`, `--json`, and `--quiet` with
+  `--output <default|verbose|quiet|json>`.
+- Keep model selection under `--model <provider/model>` and server credentials
+  under `OPENCODE_URL` and `OPENCODE_TOKEN`; the retired embedded-agent flags
+  and `RALPHIE_MODEL_*` environment variables are no longer part of the CLI.
+
+### Added
+
+- Native Bun CLI foundation with GitHub, Git, workspace, and OpenCode domain
+  explicit service factories, and an ordinary runtime dependency object.
+- Focus execution on one required repository and accept all configuration through
+  CLI arguments and flags; remove JSON configuration, named projects, repository
+  patterns, and multi-repository orchestration.
+- Use the external `@opencode-ai/client` server integration, operator-run
+  OpenCode sessions, a permission watcher and denylist for defense in depth,
+  and fenced structured-output/needs-attention responses validated by Zod.
+- Rely on the authoritative non-force Git push for GitHub branch policy and
+  permission enforcement while retaining destination, commit, and divergence
+  safety checks.
+- Render interactive progress through a bounded replaceable terminal region with
+  nested-stage tracking instead of creating an OpenTUI renderer.
+- Close completed implementation issues after verified delivery, with
+  idempotent recovery for interrupted or ambiguous GitHub responses.
+
+### Fixed
+
+- Prevent final progress events from recreating a workspace removed by
+  `--clean end`.
+- Prevent viewport repainting, split-stream output, and accumulating
+  `CliRenderer` destroy listeners during long runs.
+- Prevent no-change agent runs from being silently skipped without proving
+  whether the issue is already resolved.
+
+[Unreleased]: https://github.com/beremaran/ralphie/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/beremaran/ralphie/compare/v0.1.2...v0.2.0