Merge pull request #310 from ryaneggz/fix/297-release-changelog-sync

FROM fix/297-release-changelog-sync TO development
2026-05-17 19:06:23 -06:00
commit 1e207dead7
@@ -78,8 +78,15 @@ awk -v ver="$VERSION" -v rdate="$RELEASE_DATE" '
  { print }
 ' CHANGELOG.md > CHANGELOG.md.tmp && mv CHANGELOG.md.tmp CHANGELOG.md

+PREV_BRANCH=$(git branch --show-current)
 git add CHANGELOG.md
 git commit -m "task: promote CHANGELOG for $VERSION"
+
+# CRITICAL: push the promotion commit back to the source branch BEFORE cutting
+# the release branch (issue #297). If we only push the release branch, the
+# next round of work on $PREV_BRANCH will re-carry already-released entries
+# under [Unreleased] and the next /release will double-promote them.
+git push origin "$PREV_BRANCH"
 ```

 The `[$VERSION]` section is the source of truth for the GitHub Release body — `release.yml` extracts it via `body_path` (no `generate_release_notes`).
@@ -87,7 +94,6 @@ The `[$VERSION]` section is the source of truth for the GitHub Release body —
 ### Step 4 — Push release branch + tag

 ```bash
-PREV_BRANCH=$(git branch --show-current)
 git checkout -b "release/$VERSION"
 git push origin "release/$VERSION"
 git tag "$VERSION" && git push origin "$VERSION"    # triggers release.yml
@@ -10,15 +10,53 @@ Update policy and release automation live in [`.claude/rules/git.md`](.claude/ru

 ### Added
 - `OH_GITHUB_REPO` and `OH_GITHUB_REF` env vars for fork-friendly installs ([#309](https://github.com/ryaneggz/open-harness/pull/309)).
- `docs/connecting.md` — new runbook documenting the VSCode Attach + port-forwarding workflow for remote dev servers. Covers the "machine unreachable" debugging pattern: VS Code Remote SSH's automatic port-forwarding, manual fallback for direct-terminal users, and the `localhost:` prefix convention for accessing services on the Docker host. Referenced from `intro.md`, `quickstart.md`, `harnesses/overview.md`, `harnesses/t3code.md`, and `integrations/slack.md`. ([#300](https://github.com/ryaneggz/open-harness/issues/300))
- **Agents catalog**: new `docs/agents/` section (renamed from `docs/agents/` → `docs/harnesses/` after initial creation to match sidebar label). Includes `_category_.json` organizing the section, `overview.md` as the hub page, and five per-branch playbook pages (`portfolio-mgr.md`, `blog-writer.md`, `linkedin-ghostwriter.md`, `dc-designer.md`, `uat-tester.md`), each documenting use-case, harness selection, auth flow, and tmux launch pattern. ([#300](https://github.com/ryaneggz/open-harness/issues/300))
- `.devcontainer/docker-compose.yml` publishes container port 1455 to the host loopback (`127.0.0.1:1455:1455`) for the **Pi harness** login flow, whose OAuth callback binds `http://localhost:1455`. With the port on the host loopback, VS Code Remote SSH's automatic port-forwarding carries the redirect back to the laptop and Pi login completes out of the box; direct-terminal (plain `ssh`) users still need to forward the port manually with `ssh -L 1455:localhost:1455 user@host`. The Codex CLI is unaffected — it has its own headless path via `codex login --device-auth`. ([#287](https://github.com/ryaneggz/open-harness/issues/287))
+- `/worktrees` skill (`.claude/skills/worktrees/SKILL.md`) — orchestrator skill for managing `.worktrees/` lifecycle: create, list, remove, clean, stale audit, project clones.

 ### Changed
 - README and `docs/installation.md` add a "For forks / self-host" section; canonical upstream `oh.mifune.dev` URL unchanged ([#309](https://github.com/ryaneggz/open-harness/pull/309)).
+- `/release` skill now pushes the source branch back to origin immediately after the CHANGELOG promotion commit, before cutting the release branch. Without this, the promotion commit lived only on `release/*`, so the next round of work on `development` re-carried already-released `[Unreleased]` entries and the next `/release` would double-promote them ([#297](https://github.com/ryaneggz/open-harness/issues/297)).
+
+### Fixed
+- Repaired `CHANGELOG.md` drift between `development` and `main`: prior to the `/release` fix above, three releases (`2026.5.14`, `2026.5.15`, `2026.5.16`) had promoted versioned sections on `main` but never landed those promotions back on `development`, leaving stale `[Unreleased]` entries that duplicated already-shipped content. This commit restores the versioned sections to `development` from `main` and trims `[Unreleased]` to the genuinely new (post-`2026.5.16`) entries ([#297](https://github.com/ryaneggz/open-harness/issues/297)).
+
+### Removed
+### Deprecated
+### Security
+
+## [2026.5.16] - 2026-05-16
+
+### Added
+- `docs/connecting.md` — new runbook documenting the VSCode Attach + port-forwarding workflow for remote dev servers. Covers the "machine unreachable" debugging pattern: VS Code Remote SSH's automatic port-forwarding, manual fallback for direct-terminal users, and the `localhost:` prefix convention for accessing services on the Docker host. Referenced from `intro.md`, `quickstart.md`, `harnesses/overview.md`, `harnesses/t3code.md`, and `integrations/slack.md`. ([#300](https://github.com/ryaneggz/open-harness/issues/300))
+- **Agents catalog**: new `docs/agents/` section (renamed from `docs/agents/` → `docs/harnesses/` after initial creation to match sidebar label). Includes `_category_.json` organizing the section, `overview.md` as the hub page, and five per-branch playbook pages (`portfolio-mgr.md`, `blog-writer.md`, `linkedin-ghostwriter.md`, `dc-designer.md`, `uat-tester.md`), each documenting use-case, harness selection, auth flow, and tmux launch pattern. ([#300](https://github.com/ryaneggz/open-harness/issues/300))
+
+### Changed
 - Renamed `docs/agents/` folder to `docs/harnesses/` so the folder name matches the sidebar label; added `@docusaurus/plugin-client-redirects` to `apps/docs/` with seven redirects from `/docs/agents/*` → `/docs/harnesses/*` preserving URLs from the initial agents-catalog PR. ([#300](https://github.com/ryaneggz/open-harness/issues/300))
 - Cross-linked `docs/connecting.md` from `intro.md`, `quickstart.md`, `harnesses/overview.md`, `harnesses/t3code.md`, and `integrations/slack.md` so the VSCode attach pattern is discoverable from each major entry point. ([#300](https://github.com/ryaneggz/open-harness/issues/300))
 - Fixed `apps/README.md` script-name drift: `pnpm --filter @openharness/docs dev` → `pnpm --filter @openharness/docs start` to match the actual `start` script in `apps/docs/package.json`. ([#300](https://github.com/ryaneggz/open-harness/issues/300))
+- Docs frame the orchestrator-via-VS-Code-attach as the canonical workflow. `docs/quickstart.md` "Enter the sandbox" now leads with the VS Code Dev Containers attach flow (Command Palette → `Dev Containers: Attach to Running Container...` → `openharness`), since it works identically on localhost and over Remote-SSH; `make shell` is demoted to a terminal fallback. `docs/intro.md` "How it works" names the **orchestrator** (the agent session attached at the project root that owns git, lifecycle, and edits, drives other containers over the Docker socket, and only needs host-shell intervention for things the running container can't do for itself — typically a new bind-mounted volume), frames a second sandbox as opt-in for isolation only, and closes with a Mermaid architecture diagram (orchestrator at the center of the sandbox subgraph, tmux session row, `docker.sock` → optional second sandbox, external GitHub / LLM-provider edges, host bind-mount). `docs/harnesses/overview.md` replaces the redundant "Running an agent in tmux" section with "Default surfaces" (Pi+Slack, T3 Code, docs app on `:3000`), each as a named tmux session, with explicit guidance to open the two browser surfaces in VS Code's Simple Browser (`Ctrl+Shift+P` → `Simple Browser: Show`; `Cmd+Shift+P` on macOS) so the live UI sits next to the code being edited. Documented tmux sessions renamed `agent-pi` → `harness-pi` and `agent-t3code` → `harness-t3code` in `docs/harnesses/overview.md` only — the `oh config slack` wizard at `apps/oh/src/config/slack.ts` still creates `agent-pi`, and `context/rules/sandbox-processes.md` still defines the `agent-` prefix; full rename across wizard code, rule, and sibling docs (`docs/intro.md`, `docs/integrations/slack.md`, `docs/harnesses/t3code.md`, `.pi/extensions/slack/README.md`) will follow. ([#302](https://github.com/ryaneggz/open-harness/issues/302))
+- `.worktrees/README.md` now reserves `.worktrees/project/<owner>/<repo>/` for durable standalone repo clones and narrows `.worktrees/agent/` to harness agent branches / legacy agent-owned clones, using generic examples so the layout applies cleanly to new users. ([#295](https://github.com/ryaneggz/open-harness/issues/295), [#298](https://github.com/ryaneggz/open-harness/issues/298))
+
+### Fixed
+- Dark-mode inline `code` pills in the docs site were nearly invisible against pure-black surfaces. `apps/docs/src/css/custom.css` background bumped from `rgba(255, 255, 255, 0.06)` → `0.12`, border `0.1` → `0.22`, and text raised to pure white. Light mode untouched. ([#302](https://github.com/ryaneggz/open-harness/issues/302))
+
+### Removed
+### Deprecated
+### Security
+
+## [2026.5.15] - 2026-05-15
+
+### Added
+### Changed
+- `oh config slack` wizard UX overhaul. Token prompts now echo `●` per keystroke (was: silent — looked frozen) via a TTY-aware raw-mode `askSecret` that handles backspace, Ctrl-U, and Ctrl-C; piped/non-TTY stdin still uses the legacy readline fallback as `askSecretPiped` so `echo "" | oh config slack` keeps working. Flow is reframed into four numbered steps `[1/4] … [4/4]` with inline "Where:" hints and clickable URLs (OSC 8 hyperlinks; fall back to `label (url)` on legacy terminals). Each input shows `✓ valid prefix` / `✓ N user(s) accepted` after validation. A final summary screen lists the keys (tokens redacted, IDs visible) and gates the env-file write behind a `Proceed? [Y/n]` confirmation. New helpers exported from `apps/oh/src/lib/prompt.ts`: `step()`, `link()`, `bold()`. Zero new runtime dependencies. ([#290](https://github.com/ryaneggz/open-harness/issues/290))
+### Fixed
+### Removed
+### Deprecated
+### Security
+
+## [2026.5.14] - 2026-05-14
+
+### Added
+- `.devcontainer/docker-compose.yml` publishes container port 1455 to the host loopback (`127.0.0.1:1455:1455`) for the **Pi harness** login flow, whose OAuth callback binds `http://localhost:1455`. With the port on the host loopback, VS Code Remote SSH's automatic port-forwarding carries the redirect back to the laptop and Pi login completes out of the box; direct-terminal (plain `ssh`) users still need to forward the port manually with `ssh -L 1455:localhost:1455 user@host`. The Codex CLI is unaffected — it has its own headless path via `codex login --device-auth`. ([#287](https://github.com/ryaneggz/open-harness/issues/287))

 ### Removed
 - In-tree docker-compose overlays under `.devcontainer/` except `docker-compose.postgres.yml`: the five host-auth overlays (`claude-host.yml`, `codex-host.yml`, `opencode-host.yml`, `pi-host.yml`, `deepagents-host.yml`), the three SSH overlays (`ssh.yml`, `ssh-generate.yml`, `sshd.yml`), `git.yml`, and `cloudflared.yml`. The host-auth overlays existed to share host agent credentials when the host UID matched the sandbox's UID 1000; `.devcontainer/entrypoint.sh` now syncs the sandbox user's UID/GID to the bind-mounted repo's owner on boot (replacing the host-group-membership workaround), so files written in either direction stay readable without per-agent overlays. Agent auth still persists in named volumes (`claude-auth`, `codex-auth`, `pi-auth`, `opencode-auth`, `deepagents-auth`, `cloudflared-auth`, `gh-config`); `gh auth login` covers git over HTTPS without per-overlay setup. Postgres remains opt-in via `docker-compose.postgres.yml`. Removed companion infrastructure: `install/cloudflared-tunnel.sh`, the `/cloudflared-tunnel` skill, the `*_HOST_BIND_MOUNT` / `SANDBOX_PASSWORD` / `INSTALL_BROWSER` / `INSTALL_CLOUDFLARED` / `GIT_COMMON_DIR` / `HOST_SSH_DIR` / `HOST_*_DIR` env plumbing in `.devcontainer/entrypoint.sh`, and the host-UID overlay-stripping block in `scripts/install.sh`. Deleted doc: `docs/integrations/cloudflare.md`. The `composeOverrides[]` mechanism in `config.json` is retained so downstream packs (Pi extensions, BYO harness packs) can still register their own overlays. ([#283](https://github.com/ryaneggz/open-harness/issues/283))
@@ -27,9 +65,6 @@ Update policy and release automation live in [`.claude/rules/git.md`](.claude/ru
 - `.pi/overlays/docker-compose.slack.yml` and all references to it. The in-tree Pi extension at `.pi/extensions/slack/` reads `SLACK_APP_TOKEN` / `SLACK_BOT_TOKEN` directly from `process.env` at `session_start`, so the compose-time wiring overlay is redundant. `docs/integrations/slack.md`, `README.md`, `docs/architecture/container-runtime.md`, `docs/guide/bring-your-own-harness.md`, `.devcontainer/docker-compose.yml`, and `.devcontainer/.example.env` no longer reference the overlay; `.pi/overlays/` directory removed. Source of truth for Slack env wiring is `.pi/extensions/slack/README.md`.

 ### Changed
- Docs frame the orchestrator-via-VS-Code-attach as the canonical workflow. `docs/quickstart.md` "Enter the sandbox" now leads with the VS Code Dev Containers attach flow (Command Palette → `Dev Containers: Attach to Running Container...` → `openharness`), since it works identically on localhost and over Remote-SSH; `make shell` is demoted to a terminal fallback. `docs/intro.md` "How it works" names the **orchestrator** (the agent session attached at the project root that owns git, lifecycle, and edits, drives other containers over the Docker socket, and only needs host-shell intervention for things the running container can't do for itself — typically a new bind-mounted volume), frames a second sandbox as opt-in for isolation only, and closes with a Mermaid architecture diagram (orchestrator at the center of the sandbox subgraph, tmux session row, `docker.sock` → optional second sandbox, external GitHub / LLM-provider edges, host bind-mount). `docs/harnesses/overview.md` replaces the redundant "Running an agent in tmux" section with "Default surfaces" (Pi+Slack, T3 Code, docs app on `:3000`), each as a named tmux session, with explicit guidance to open the two browser surfaces in VS Code's Simple Browser (`Ctrl+Shift+P` → `Simple Browser: Show`; `Cmd+Shift+P` on macOS) so the live UI sits next to the code being edited. Documented tmux sessions renamed `agent-pi` → `harness-pi` and `agent-t3code` → `harness-t3code` in `docs/harnesses/overview.md` only — the `oh config slack` wizard at `apps/oh/src/config/slack.ts` still creates `agent-pi`, and `context/rules/sandbox-processes.md` still defines the `agent-` prefix; full rename across wizard code, rule, and sibling docs (`docs/intro.md`, `docs/integrations/slack.md`, `docs/harnesses/t3code.md`, `.pi/extensions/slack/README.md`) will follow. ([#302](https://github.com/ryaneggz/open-harness/issues/302))
- `.worktrees/README.md` now reserves `.worktrees/project/<owner>/<repo>/` for durable standalone repo clones and narrows `.worktrees/agent/` to harness agent branches / legacy agent-owned clones, using generic examples so the layout applies cleanly to new users. ([#295](https://github.com/ryaneggz/open-harness/issues/295), [#298](https://github.com/ryaneggz/open-harness/issues/298))
- `oh config slack` wizard UX overhaul. Token prompts now echo `●` per keystroke (was: silent — looked frozen) via a TTY-aware raw-mode `askSecret` that handles backspace, Ctrl-U, and Ctrl-C; piped/non-TTY stdin still uses the legacy readline fallback as `askSecretPiped` so `echo "" | oh config slack` keeps working. Flow is reframed into four numbered steps `[1/4] … [4/4]` with inline "Where:" hints and clickable URLs (OSC 8 hyperlinks; fall back to `label (url)` on legacy terminals). Each input shows `✓ valid prefix` / `✓ N user(s) accepted` after validation. A final summary screen lists the keys (tokens redacted, IDs visible) and gates the env-file write behind a `Proceed? [Y/n]` confirmation. New helpers exported from `apps/oh/src/lib/prompt.ts`: `step()`, `link()`, `bold()`. Zero new runtime dependencies. ([#290](https://github.com/ryaneggz/open-harness/issues/290))
 - Migrate `.pi/extensions/slack/{index,tools}.ts` from the deprecated `@mariozechner/pi-coding-agent` (and `@mariozechner/pi-agent-core`) to the upstream-recommended successors `@earendil-works/pi-coding-agent` (and `@earendil-works/pi-agent-core`). Per `npm view @mariozechner/pi-coding-agent`'s deprecation notice, the old package is no longer maintained. The other two in-tree extensions (`path-guard.ts`, `plan-mode/index.ts`) had already migrated; slack was the laggard. `.devcontainer/Dockerfile`'s `[pi-coding-agent]` mapping in the `PKG` array, `docs/agents/pi.md`'s upstream link, `docs/installation.md`'s Pi row, and `.pi/UPSTREAM.md`'s lineage label all updated to match. ([#281](https://github.com/ryaneggz/open-harness/issues/281))
 - `docs/integrations/slack.md` § 5 leads with the new `oh config slack` wizard; the manual `set -a; source ...; tmux new-session` ritual is demoted to a `<details>` "Manual fallback" collapsible. Sections renumbered (8→7, 9→8). The wizard explicitly **starts the Slack bridge for you** at the end — kills any existing `agent-pi` tmux session, launches a fresh one running `pi` with the new env sourced, and polls `tmux capture-pane` for the `connected and listening` log line. ([#281](https://github.com/ryaneggz/open-harness/issues/281))
 - Sidebar label `Agents` → `Harnesses` in `docs/agents/_category_.json` (and corresponding `Harnesses Overview` H1 in `docs/agents/overview.md`). The "Pick your harness" section in `docs/quickstart.md` now links each harness to its per-harness page and adopts the t3code "authenticate at least one provider before use" framing across Codex (`codex login`), OpenCode (`opencode auth login`), Claude (OAuth on first launch), Pi (env vars), DeepAgents (`~/.deepagents/.env`), and the new T3 Code (`npx t3` + pairing URL). Per-harness pages updated with matching Authentication sections. ([#281](https://github.com/ryaneggz/open-harness/issues/281))
@@ -39,7 +74,6 @@ Update policy and release automation live in [`.claude/rules/git.md`](.claude/ru
 - Full rewrite of `docs/integrations/slack.md` to document ID allowlist semantics, Socket Mode smoke test, the token-freshness pattern, and migration from the legacy `@ryaneggz/mifune` pack; `docs/quickstart.md` adds a "Next steps" section pointing to integration pages. References to the stale `@ryaneggz/mifune` Slack context pack removed from `README.md`, `docs/installation.md`, `docs/agents/pi.md`, and `docs/agents/overview.md`. ([#279](https://github.com/ryaneggz/open-harness/issues/279))

 ### Fixed
- Dark-mode inline `code` pills in the docs site were nearly invisible against pure-black surfaces. `apps/docs/src/css/custom.css` background bumped from `rgba(255, 255, 255, 0.06)` → `0.12`, border `0.1` → `0.22`, and text raised to pure white. Light mode untouched. ([#302](https://github.com/ryaneggz/open-harness/issues/302))
 - Docusaurus marketing landing page hero quickstart still showed `cd ~/openharness && make shell`, leaving new users at "no such directory" after the curl-pipe install. Updated `apps/docs/src/pages/index.tsx` to `cd ~/.openharness && make shell` to match the installer rename in [#200](https://github.com/ryaneggz/open-harness/issues/200) / [#210](https://github.com/ryaneggz/open-harness/issues/210). The same rename had already landed in `README.md`, `docs/quickstart.md`, and `docs/installation.md`; the JSX template literal in the home page was the last copy still pointing at the old path.
 - `pi` failing on a fresh sandbox with `Failed to load extension "/home/sandbox/harness/.pi/extensions/slack/index.ts": Cannot find module '@slack/socket-mode'`. The in-tree Slack Pi extension imports `@slack/socket-mode`, `@slack/web-api`, and `chalk`, all declared in the root `package.json` but never installed automatically — the harness is bind-mounted, so a Dockerfile-time install would be shadowed at runtime. `.devcontainer/entrypoint.sh` now runs `pnpm install --prefer-offline` at the harness root on first boot when `node_modules/` is missing, before the cron runtime starts (which itself imports `croner` from the same `package.json`). Set `SKIP_PNPM_INSTALL=1` to opt out.
 - Docs landing page supported-agent copy and agent grid now include DeepAgents with a matching icon tile.