docs(integration): add merge log/summary formats and an integration-branch skill [skip-ci] - #675
Merged
Merged
Conversation
…ranch skill [skip-ci] Ports the two document formats and the skill from tb-streamer, keeping the section structure identical so the two repos' integration logs stay comparable, and adapts everything that differs here. Verification is the five checks that gate main — Lint, Type check, Unit tests, Integration tests, i18n — because test:unit alone is a false green and integration is a separate Jest run. The CI step records that the Jest E2E job is advisory and that Maestro E2E never runs on a PR, so a PR whose flows were never dispatched is E2E unknown rather than E2E green. The conflict ledger names the two classes that recur here: version-bump collisions, which are mechanical, and native deps or patches, which are never mechanical and are only verified by check:native-deps plus a real build. When the set is resolved the skill lists any draft PRs in it and asks whether the run includes them, rather than inferring an answer, and never flips a draft ready to build a branch. The skill is bound to this repo's own rule from the 2026-08-12 retirement — an integration branch is a staging area with an expiry, not a parallel trunk. It opens by citing that decision, forbids committing fixes to the branch, and ends by retiring it using the audit that made the deletions safe: ask whether a ref holds a file main has never had, not whether it is merged. The skills README records that discovery is automatic, that _shared is not a skill, and that writing the skip tag by hand — or merely quoting it in a commit body — makes the commit-msg hook exit before its path check. [skip-ci]
RonenMars
added a commit
to RonenMars/threadbase-streamer
that referenced
this pull request
Aug 12, 2026
… [skip-ci] Once the set is resolved, the integration-branch skill lists every draft PR in it and asks whether this run includes them, before the branch is cut rather than at the merge that happens to hit one. The answer is never inferred: a PR is draft because it is unfinished, or because its author is blocked on something with nothing to do with the code, and those want opposite treatment. Including a draft does not require flipping it ready, since the skill merges the PR's head locally and the draft flag only gates merging on GitHub. The identical wording is in the tb-mobile copy of this skill (RonenMars/threadbase-mobile#675).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Ports the two integration document formats and the integration-branch skill from tb-streamer, and adds a README for the skills folder.
The section structure of both formats is byte-for-byte the same shape as the streamer copies, so the two repos' integration logs stay comparable; everything that differs here is adapted.
What is here
docs/integration/log-format.md— the live merge log, appended after every action during a run.docs/integration/summary-format.md— the end-of-run summary, derived from the log..claude/skills/integration-branch/SKILL.md— the skill that runs the integration and writes both..claude/skills/README.md— how skills are discovered here, and the conventions for adding one.Adapted for this repo
Verification is the five checks that gate
main— Lint, Type check, Unit tests, Integration tests, i18n — at the baseline and at every checkpoint.test:unitalone is a false green: integration is a separate Jest run and is where a changed guard on a shared function actually surfaces.check:native-depsand a real build are required whenever the set touches a native dependency,patches/,ios/orandroid/, because Jest never sees any of it.The CI step records which checks are required and which are not: the Jest E2E job runs on every PR but is advisory, and Maestro E2E never runs on a PR at all.
A PR whose Maestro flows were never dispatched is E2E unknown, not E2E green.
The conflict ledger names the two classes that recur here — version-bump collisions, which are mechanical and resolve by taking the higher value, and native deps or patches, which are never mechanical whatever the diff looks like.
Bound to the branch-retirement decision
The skill operates under this repo's own rule from 2026-08-12: an integration branch is a staging area with an expiry, not a parallel trunk.
It cites that decision up front, forbids committing fixes to the integration branch, and ends with a retirement step that reuses the audit which made the deletions safe — ask whether a ref holds a file
mainhas never had, rather than whether it is merged.Drafts are the user's call: once the set is resolved the skill lists any draft PRs and asks whether the run includes them, and it never flips a draft ready in order to build a branch.
Verification
Every npm script the documents quote exists in
package.json, and every relative link resolves.The one link that did not — the retirement doc, still open in #666 — is cited by path instead, to be linked once that PR lands.
Documentation and skill markdown only; the
commit-msghook applied the skip tag itself.