Repository navigation
Shape release workflow and user migration docs - #5
Merged
Merged
Conversation
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 28 minutes and 36 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (101)
WalkthroughAdds a shaped-release doctrine, runbook, and filesystem layout for internal release packets and user-facing release notes; introduces four repository invariants; standardizes YAML frontmatter across docs; extracts a Zod-validated domain/API surface; adds MCP server and GitHub issue sync adapter; and expands tests to cover these features. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant CLI as method sync github
participant Adapter as GitHubAdapter
participant Workspace
participant FS as Backlog Files
participant GitHub as GitHub API
User->>CLI: run "method sync github"
CLI->>CLI: validate GITHUB_TOKEN & GITHUB_REPO
CLI->>Adapter: new GitHubAdapter({workspace,token,owner,repo})
CLI->>Adapter: syncBacklog()
Adapter->>Workspace: request status/backlog items
Workspace-->>Adapter: [BacklogItem...]
loop per item
Adapter->>FS: readFrontmatter(path)
FS-->>Adapter: frontmatter
alt frontmatter.github_issue_id exists
Adapter-->>Adapter: mark skipped
else
Adapter->>FS: readHeading(path)
FS-->>Adapter: title
Adapter->>FS: readBody(path)
FS-->>Adapter: body
Adapter->>GitHub: POST /repos/{owner}/{repo}/issues
GitHub-->>Adapter: {id, number, html_url}
Adapter->>FS: updateFrontmatter(github_issue_id, github_issue_url)
Adapter-->>Adapter: return success
end
end
Adapter-->>CLI: results array
CLI-->>User: print summary (stdout/stderr)
sequenceDiagram
participant Client
participant Stdio as StdioTransport
participant MCP as MCP Server
participant Workspace
participant Domain as Domain Logic
Client->>Stdio: CallToolRequest(method_status)
Stdio->>MCP: deliver request
MCP->>Workspace: Workspace.status()
Workspace->>Domain: collect backlog/activeCycles/legendHealth
Domain-->>Workspace: WorkspaceStatus
Workspace-->>MCP: serialized text result
MCP-->>Stdio: tool response
Stdio-->>Client: returned status text
Estimated code review effort🎯 4 (Complex) | ⏱️ ~50 minutes Possibly related PRs
Poem
✨ Finishing Touches🧪 Generate unit tests (beta)
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/method/release-runbook.md`:
- Around line 90-91: Replace the two-step "Push `main`" and "Push the exact
release tag" with a single atomic push that publishes the branch and its tag
together (i.e., push both the main ref and the release tag in one command or use
the git option that follows tags) so the commit and tag are never partially
published; update the runbook steps around "Push `main`" / "Push the exact
release tag" to describe this single atomic push and include the exact
invocation to run in your environment.
In
`@docs/method/retro/0008-release-shaping-and-user-migration-docs/witness/verification.md`:
- Around line 59-63: The witness file records Vitest version "v4.1.2" but your
package.json/package-lock.json declare "vitest@^4.0.18", causing a mismatch;
update the witness entry in verification.md to the locked version "v4.0.18" (or
regenerate the witness while locking vitest to 4.1.2) so the recorded runtime
matches the dependency lock, ensuring reproducible test results.
In `@tests/docs.test.ts`:
- Around line 326-335: The test currently only checks each heading exists, so
update the test that reads the runbook via readRepoFile and asserts the headings
appear in the expected order by checking the index/position of each heading
(e.g., using runbook.indexOf('# Release Runbook') and subsequent
runbook.indexOf('## Phase 0: Discovery'), '## Phase 1: Guards', '## Phase 2:
Versioning and release notes', '## Phase 3: Validation', '## Phase 4: Commit,
tag, and publish', '## Abort conditions') and asserting each subsequent index is
greater than the previous using the existing expect helper; this ensures the
headings are present and in sequential order rather than merely existing
anywhere in the file.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: f3aa3dc2-263e-45cb-a3be-68c29bf571be
📒 Files selected for processing (14)
README.mddocs/design/0008-release-shaping-and-user-migration-docs/release-shaping-and-user-migration-docs.mddocs/method/backlog/inbox/PROCESS_release-shaping-and-user-migration-docs.mddocs/method/release-runbook.mddocs/method/release.mddocs/method/releases/README.mddocs/method/retro/0008-release-shaping-and-user-migration-docs/release-shaping-and-user-migration-docs.mddocs/method/retro/0008-release-shaping-and-user-migration-docs/witness/README.mddocs/method/retro/0008-release-shaping-and-user-migration-docs/witness/playback.mddocs/method/retro/0008-release-shaping-and-user-migration-docs/witness/verification.mddocs/releases/README.mdsrc/workspace.tstests/cli.test.tstests/docs.test.ts
💤 Files with no reviewable changes (1)
- docs/method/backlog/inbox/PROCESS_release-shaping-and-user-migration-docs.md
Owner
Author
|
Resolved review feedback on PR #5.
Validation on the current branch tip:
|
Owner
Author
|
@coderabbitai review please 🥕 |
|
🧠 Learnings used✅ Actions performedReview triggered.
|
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/method/release-runbook.md`:
- Around line 15-20: Revise the four release-runbook bullets so they no longer
all begin with "Abort immediately if …" while preserving the same checks:
rewrite the working-tree bullet to start with a command (e.g., "Ensure the
working tree is clean; abort if dirty"), rewrite the branch sync bullet to state
the required condition first (e.g., "main must be exactly synced with
origin/main; abort if not"), rephrase the tools/credentials/signing/CI/registry
bullet to list missing prerequisites then indicate abort, and reword the
validation/publish-verification bullet to lead with the required checks then the
abort action; keep the checks and strictness identical.
In `@tests/docs.test.ts`:
- Around line 326-346: The test 'ships a release runbook that separates doctrine
from pre-flight execution' currently only asserts that '## Abort conditions'
exists; modify the assertions around the runbook variable so you also fetch the
index of '## Abort conditions' (e.g., abortIndex = runbook.indexOf("## Abort
conditions")) and assert that abortIndex is >= 0 and abortIndex is less than the
index of '## Phase 0: Discovery' (the Phase 0 index already obtained via the
phases loop or by computing phase0Index = runbook.indexOf("## Phase 0:
Discovery")); keep the existing presence and order checks but add these two
assertions to ensure Abort conditions appears before Phase 0.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 97f7dd1d-314c-49f0-a5e9-336581498ec5
📒 Files selected for processing (5)
docs/method/backlog/inbox/PROCESS_yaml-frontmatter-schema.mddocs/method/release-runbook.mddocs/method/retro/0008-release-shaping-and-user-migration-docs/release-shaping-and-user-migration-docs.mddocs/method/retro/0008-release-shaping-and-user-migration-docs/witness/verification.mdtests/docs.test.ts
Invariants are named properties that must remain true across all cycles. They live in docs/invariants/<name>.md and give legends a concrete job: guard the invariant and ask at every playback whether it still holds. - Added Invariants section to README before Legends - Added docs/invariants/ to the canonical directory structure - Updated Legends section to reference invariant guardianship - Updated process.md drift check to include invariant preservation - Updated CHANGELOG
Four invariants for this repo: - cycle-traceability: every cycle is discoverable and ends with a retro - commitment-integrity: pulled work doesn't go back to the backlog - signpost-provenance: generated signposts cite sources and context - signpost-boundedness: signposts stay shallow and never create commitments Legend docs and README descriptions now name the invariants they guard.
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/invariants/commitment-integrity.md`:
- Line 17: The current invariant sentence "A design doc in
`docs/design/<cycle>/` means someone is committed." is too narrow and should be
broadened to include release-first artifacts; update the wording in
commitment-integrity.md to treat either a design doc under
`docs/design/<cycle>/` OR release-related artifacts (e.g.,
`docs/releases/<cycle>/`, `release/*`, or other release-surface directories used
by this repo) as evidence of commitment, and then adjust any enforcement rules
or scripts that reference that exact path-pattern so they check for both
`docs/design/<cycle>/` and the release artifact patterns.
In `@docs/invariants/signpost-boundedness.md`:
- Line 20: The phrase "below `docs/`" is ambiguous and may ban files like
`docs/BEARING.md`; update the invariant wording in
docs/invariants/signpost-boundedness.md to explicitly ban only files nested more
than one level under docs/, e.g. state "no `ALL_CAPS.md` files may exist in any
subdirectory deeper than one level under `docs/` (paths matching `docs/*/*` or
deeper)", so single-level files like `docs/BEARING.md` remain allowed.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 626ff06b-53a3-4356-9496-df0d048631c9
📒 Files selected for processing (11)
CHANGELOG.mdREADME.mddocs/invariants/commitment-integrity.mddocs/invariants/cycle-traceability.mddocs/invariants/signpost-boundedness.mddocs/invariants/signpost-provenance.mddocs/method/backlog/cool-ideas/SYNTH_cycle-witness-command.mddocs/method/backlog/up-next/PROCESS_git-branch-workflow-policy.mddocs/method/legends/PROCESS.mddocs/method/legends/SYNTH.mddocs/method/process.md
Owner
Author
|
Resolved review feedback on PR #5.
Validation on the current branch tip:
@coderabbitai review please 🥕 |
|
🧠 Learnings used✅ Actions performedReview triggered.
|
Owner
Author
|
@coderabbitai review please |
|
🧠 Learnings used✅ Actions performedReview triggered.
|
Owner
Author
|
@coderabbitai looks like you couldn't post? |
|
🧠 Learnings used✅ Actions performedReview triggered.
|
This was referenced Apr 5, 2026
This was referenced Apr 7, 2026
Merged
This was referenced Jun 1, 2026
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.
What changed
This PR shapes releases as first-class METHOD artifacts instead of treating tagging and changelog edits as an afterthought.
It adds:
docs/method/release.mddocs/method/release-runbook.mddocs/method/releases/docs/releases/method initscaffolding for the new release surfaces0008cycle packet with retro and witnessPROCESS_yaml-frontmatter-schemaWhy it changed
The existing release doctrine was too thin for the repo's current level of rigor. METHOD already knows how to close cycles honestly, but it did not yet define how to shape a release, justify a version, separate internal release truth from user-facing release notes, or keep release work from distorting backlog topology.
This cycle makes those boundaries explicit.
Impact
docs/method/releases/anddocs/releases/CHANGELOG.mdremains the ledger, not the only user-facing release surfacedocs/method/backlog/<version>/directoriesmainand the tag as one atomic delivery stepValidation
npm testnpm run buildnpm run method -- status