Skip to content

docs(solutions): capture nine learnings from the dual-host and Fro Bot work - #590

Merged
marcusrbrown merged 3 commits into
mainfrom
docs/compound-batch-2026-11-21
Nov 21, 2026
Merged

marcusrbrown merged 3 commits into
mainfrom
docs/compound-batch-2026-11-21

Conversation

@marcusrbrown

Copy link
Copy Markdown
Owner

This PR runs a ce:compound round in full mode over the 2026-11-20/21 work, beyond the dual-host doc that #588 already merged. It has three parallel drafters (L1–L9, every claim checked against code, PRs and git history) and a Related Docs Finder that scores each doc for overlap. All new docs scored Low or Moderate against existing ones, so they are new files. L4 scored High against the re-entrant dialog doc, so that doc is updated in place.

# Doc Category
L1 Fro Bot autoheal fixes discarded because output-mode was never set (#555) integration-issues
L2 Comment-triggered Fro Bot runs checked out fork PR heads on a runner holding FRO_BOT_PAT (#555) security-issues (new)
L3 Biome markdown formatting corrupted docs frontmatter and failed the changesets release PR (#492, #516 → #564, #566, #588) build-errors (new)
L4 Re-entrant dialog doc updated: host dialogs are now the shipped design, slashName, V2 mode: 'global' (#572, #587) ui-bugs
L5 Stale RPC port files leaked one cache dir per dead process (#573, #575) logic-errors (new)
L6 Test env restore stored the string "undefined", and wall-clock races flaked the suite (#567, #569) test-failures (new)
L7 Use a version-scoped Bun override key for a deep transitive advisory (#568) best-practices
L8 V2 TUI finds the server's RPC port file by the server pid (#587) best-practices
L9 Isolate OpenCode live checks in a scratch rig outside the checkout workflow-issues

Also in this PR:

  • Frontmatter repair: 4 more docs had broken frontmatter: one ideation doc, two brainstorms and one research doc. Each is restored byte-for-byte to its frontmatter from before the Biome 2.6.2 bump, with the body unchanged.
  • tests/docs-frontmatter.test.ts: every docs/**/*.md frontmatter block must parse, and solution docs must carry title, date, category and problem_type. A formatter can no longer silently break systematic_search.
  • tests/fixtures/bin/copilot: the shim now fails with exit 66 when its fixture is missing, instead of exiting 0 with no output (the A Copilot run that exits 0 with no events and no final message is reported as complete #579 class).
  • Refresh notes:
    • the OpenTUI plan is marked completed, with the Bun override outcome;
    • the AGENTS.md Biome exclusions;
    • caveats added to the two-entrypoint, pid-file and reliable-CLI docs;
    • the plan 002 cleanup line;
    • a resolution note in research §6.

Gates:

  • lint and typecheck are clean.
  • test:unit is 474/0, including the new frontmatter test.
  • test:tui is 64/0.
  • run-host.sh v1-current PASSES with the hardened shim.
  • All 31 frontmatter blocks parse.
  • Every repo path cited in the new docs exists. The only stale references left are in historical plans that predate the deletions.

…t work

ce:compound (full mode) round over the 2026-11-20/21 work:
- new: Fro Bot autoheal fixes discarded (output-mode), fork-PR head checkout
  with the bot PAT, Biome corrupting frontmatter/CHANGELOG, stale RPC port-file
  leak, test env 'undefined' restore + wall-clock flakes, Bun version-scoped
  override, V2 TUI server discovery by pid, live-check rig isolation
- updated: re-entrant dialog doc (host dialogs are now the shipped design;
  slashName; V2 mode:'global')
- repair frontmatter of 4 brainstorm/ideation/research docs; add
  tests/docs-frontmatter.test.ts so a formatter can't silently break indexing
- harden tests/fixtures/bin/copilot to fail on a missing fixture (#579 class)
- refresh notes: OpenTUI plan completed, AGENTS.md Biome exclusions, sweep and
  discriminator caveats in older docs, research section 6 resolution
@fro-bot fro-bot added the agent: working Agent is currently working on this label Nov 21, 2026

@fro-bot fro-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: PASS

This PR changes documentation, one new unit test and one test shim. It adds no runtime plugin code. I checked the new and changed docs against the current source, package.json, biome.json and .github/workflows/fro-bot.yaml, and they match. I found no blocking issues.

Review method: I loaded ce:review in mode:read-only base:origin/main, but I did not dispatch the persona agents or run the screen/merge pipeline. The diff has no production TypeScript, so I reviewed it directly against the pinned base (df8155b). Every claim below was checked against the repository files. I ran no build, lint, typecheck or test commands.

Blocking issues

None

Non-blocking concerns

  1. tests/docs-frontmatter.test.ts:8,14-15: the frontmatter regex can match too far.
    • ^---\n([\s\S]*?)\n---\n is lazy. If a formatter or hand edit removes the closing ---, it matches up to a later --- horizontal rule in the body.
    • That could parse body text as YAML and either throw (a loud failure, which is acceptable) or pass wrongly.
    • It would be tighter to assert that the captured block contains no markdown headings, or to require the closing fence on its own line followed by a blank line or the end of the file.
    • The corruption mode that actually happened (re-indented keys) is caught by the current test, so this is hardening, not a defect.
  2. AGENTS.md architecture tree is missing files that the new docs cite.
    • src/runtime/rpc-paths.ts and src/runtime/rpc-port-sweep.ts both exist, and the new learnings and the two-entrypoint doc refer to them. Neither appears in the runtime/ listing.
    • tests/helpers/env.ts is cited by the test-flake doc and is not listed under tests/ either.
    • The omission predates this PR, but this PR is what makes the docs lean on those files.
  3. docs/solutions/build-errors/biome-markdown-formatter-corrupts-...md uses wording that goes stale.
    • Line 83 says "This PR also adds a Bun.YAML.parse frontmatter check". A durable learning should name the test file (tests/docs-frontmatter.test.ts) instead.
    • The doc says #588 repaired 10 docs but does not mention the four extra docs repaired here. The body of tests/docs-frontmatter.test.ts already lists them as covered, so a one-line mention would close the gap.
  4. docs/solutions/best-practices/per-instance-pid-files-...md (Related section): the new bullet is followed by a blank line, so the list is split from the existing "See …" bullets. Docs formatting is off, so nothing will fix this automatically.
  5. tests/fixtures/bin/copilot (shim) behaviour change.
    • The shim now exits 66 when happy-path.jsonl is missing. The old shim exited 0 with no output, so this is the right change (the #579 class).
    • The final exit status is now cat's rather than a hardcoded exit 0. That is fine under set -eu.
    • The shim still hard-sleeps 1s, which is acceptable because it is only used by tests/host-contract/.

Missing tests

None. The new tests/docs-frontmatter.test.ts is itself the regression guard for the Biome-corruption class. It runs under test:unit because it matches tests/*.test.ts, and Bun.YAML is already used in tests/host-contract-pins.test.ts.

A negative-path test would be optional: a small fixture string that is known to be corrupt and is asserted to throw. The suite already asserts that a corrupt block would fail, so this is nice to have only.

Risk assessment (LOW)

  • Regression likelihood: very low. There are no changes under src/, dist output, package.json or workflows. The only executable changes are a test file and a fixture shim that only the host-contract matrix uses.
  • Security: no secrets, PATs, tokens or PII in the new docs. I grepped docs/solutions for token patterns (ghp_, github_pat_, sk-…, private-key headers) and found nothing. The docs mention FRO_BOT_PAT and bearer tokens only by name.
  • Doc accuracy: the claims I spot-checked hold.
    • The fro-bot.yaml details match the workflow: the prehead step, trusted-head-sha, the author_association gates, output-mode, the approval-backstop job and persist-credentials: false.
    • The "brace-expansion@2": "^2.1.8" override and the prepublishOnly script match package.json.
    • The Biome exclusions match biome.json.
    • The dialog and registration details match src/tui/index.tsx and status-dialogs.tsx. The V2 mode: 'global' layer and slashName: 'copilot-status' are both present.
    • rpc-port-sweep.ts, rpc-paths.ts and tests/rpc-port-sweep.test.ts exist, as does the log line removed N stale RPC port file(s) from exited sessions.
    • tests/helpers/env.ts also exists.
  • Protected artifacts: the edits under docs/brainstorms, docs/plans, docs/research and docs/solutions are in-place refreshes. None removes a document.
  • Changeset: none is needed. There is no user-visible change to the published package.
  • Blast radius on a parent OpenCode session: none. Nothing here ships in dist.

Run Summary
Field Value
Event pull_request
Repository marcusrbrown/opencode-copilot-delegate
Run ID 44915879478
Cache hit
Session ses_e016a9f6bffevGoK0fYJgvXS6R

@fro-bot fro-bot removed the agent: working Agent is currently working on this label Nov 21, 2026
…ening)

- AGENTS.md tree lists rpc-paths.ts, rpc-port-sweep.ts, tests/helpers/env.ts
  and tests/host-contract/, which the new learnings cite
- L3 names tests/docs-frontmatter.test.ts instead of 'this PR' and records the
  four extra docs repaired in #590
- frontmatter test rejects a block containing a markdown heading (a missing
  closing fence) and pins that the Biome corruption shape fails to parse
- pid-files Related list no longer split by a blank line
@marcusrbrown

Copy link
Copy Markdown
Owner Author

Here is how each review note was handled, in 78e5a75:

  1. The lazy frontmatter regex can run past a missing closing fence. I hardened the test: a captured block containing a markdown heading now fails. I also added the optional negative test, which checks that the shape Biome actually produced (keys indented under a list item) throws.
  2. The AGENTS.md tree is missing cited files. Fixed. It now lists rpc-paths.ts, rpc-port-sweep.ts, tests/helpers/env.ts and tests/host-contract/.
  3. The L3 wording will go stale. Fixed. The doc names tests/docs-frontmatter.test.ts instead of saying "this PR", and it records the four extra docs that docs(solutions): capture nine learnings from the dual-host and Fro Bot work #590 repaired.
  4. The pid-files Related list was split by a blank line. Fixed.
  5. The shim's behaviour changed. That was intended, as you said. No change.

tests/docs-frontmatter.test.ts passes 54/0 and lint is clean.

@fro-bot fro-bot added the agent: working Agent is currently working on this label Nov 21, 2026

@fro-bot fro-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: PASS

This is a re-review of the new commit 78e5a75. I read the delta against 2af84b7. It only touches AGENTS.md, two docs and tests/docs-frontmatter.test.ts, and it addresses every note from my earlier review. I ran no build, lint, typecheck or test commands. I reviewed the diff directly and did not dispatch the ce:review personas, since nothing under src/ changed.

Blocking issues

None

Non-blocking concerns

  1. tests/docs-frontmatter.test.ts heading guard is slightly broader than its comment says.
    • /^#{1,6} /m also matches a column-0 YAML comment line such as # note, which is valid frontmatter.
    • No existing doc trips it (the author reports 54/0), and a false failure would be loud and easy to fix, so I would leave it as is.
    • If it ever fires on a legitimate comment, switch to a pattern that excludes comments or add a short allow note.

Missing tests

None. The new negative test (rejects the corruption Biome produced) pins the exact failure shape from #492, which was keys indented under a list item. The heading assertion covers the lazy-fence case.

Risk assessment (LOW)

  • Review follow-ups resolved: each of my earlier non-blocking notes is addressed in the diff.
    • AGENTS.md now lists rpc-paths.ts, rpc-port-sweep.ts, tests/helpers/env.ts and tests/host-contract/.
    • The Biome doc now names tests/docs-frontmatter.test.ts instead of "this PR" and records the four extra docs repaired in #590.
    • The stray blank line in the pid-file Related list is gone.
  • Regression likelihood: very low. The only executable change in the delta is test code, and the earlier shim change is unchanged.
  • Security: no secrets, tokens or PII added. The delta is prose plus a test with synthetic YAML.
  • Changeset: none needed, because nothing user-visible ships.
  • Blast radius on a parent OpenCode session: none. Nothing in this PR ships in dist.

Run Summary
Field Value
Event pull_request
Repository marcusrbrown/opencode-copilot-delegate
Run ID 44916274319
Cache hit
Session ses_e016a9f6bffevGoK0fYJgvXS6R

@fro-bot fro-bot removed the agent: working Agent is currently working on this label Nov 21, 2026
@fro-bot fro-bot added the agent: working Agent is currently working on this label Nov 21, 2026

@fro-bot fro-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: PASS

This is a re-review of b01a9d4, a merge of origin/main into the PR branch. The merge brings in only #589. The PR's own changes (22 files, +946/-109) are unchanged from the version I approved at 78e5a75. I reviewed the diff directly and did not dispatch the ce:review personas. I ran no build, lint, typecheck or test commands.

Blocking issues

None

Non-blocking concerns

None. The earlier note about the heading guard in tests/docs-frontmatter.test.ts still stands as a minor hardening idea, but it is not new.

Missing tests

None. #589 ships its own coverage in tests/host-contract-pins.test.ts (+41 lines), and I did not review it as part of this PR.

Risk assessment (LOW)

  • What the merge brought in: .github/renovate.json5 gains an allowedVersions: '<=0.8.4' hold on @opentui/core and @opentui/solid. tests/host-contract-pins.test.ts gains the matching test. Both come from main, not from this PR.
  • Doc consistency: the OpenTUI plan note in this PR says "The dev pin is 0.8.4 (Renovate hold in #589)". That matches the merged hold, and package.json pins @opentui/core and @opentui/solid at 0.8.4 and @opentui/core at 0.8.4 in overrides.
  • Regression likelihood: very low. The PR still changes no runtime code. Its only executable changes are the docs-frontmatter test and the fixture shim, and neither ships in dist.
  • Security: no secrets, tokens or PII added.
  • Changeset: none needed, because nothing user-visible ships.
  • Blast radius on a parent OpenCode session: none.

Run Summary
Field Value
Event pull_request
Repository marcusrbrown/opencode-copilot-delegate
Run ID 44916667438
Cache hit
Session ses_e016a9f6bffevGoK0fYJgvXS6R

@fro-bot fro-bot removed the agent: working Agent is currently working on this label Nov 21, 2026
@marcusrbrown
marcusrbrown merged commit ef252e5 into main Nov 21, 2026
9 checks passed
@marcusrbrown
marcusrbrown deleted the docs/compound-batch-2026-11-21 branch November 21, 2026 15:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants