Use rebase merges and allow safe history rewriting

AGENTS.md

@@ -11,10 +11,16 @@ release metadata, tags, or GitHub settings.
   `develop`. Ordinary development requests do not authorize promotion to `main`.
 - Inspect git status before editing and preserve unrelated work. Stage only
   your changes; never discard or commit unrelated user changes.
-- Never force-push `main` or `develop`, delete either branch, move published
-  release tags, change the default branch, or bypass CI as a routine fix.
-- Unlocking or moving `main` requires an explicit release instruction from the
-  owner. Keep it locked throughout ordinary development and review.
+- Use rebase merging for all PRs. Do not create merge commits or squash commits;
+  rebase feature branches onto the current target branch when updating them.
+- History rewriting is allowed for rebase and history cleanup. Fetch first,
+  inspect the affected commits, and push with
+  `--force-with-lease` bound to the expected remote SHA, never plain `--force`.
+  Preserve unrelated work and rerun required checks on rewritten revisions.
+- Never delete `main` or `develop`, move published release tags, change the
+  default branch, or bypass CI as a routine fix.
+- Unlocking or moving `main` requires an explicit release or history-repair
+  instruction from the owner. Relock it immediately after the authorized work.
 
 ## CI and delivery
 
@@ -25,6 +31,8 @@ release metadata, tags, or GitHub settings.
 - Before merging, both GitHub checks `test` and `windows-check` must pass on the
   current PR revision, with the branch up to date and conversations resolved.
   No additional reviewer is required for this solo-maintainer repository.
+- Rebase merge with the checked head SHA. For an authorized integration-branch
+  rewrite, follow the lease and protection-restoration steps in RELEASING.md.
 - Fix failures without weakening, skipping, or renaming required checks to
   evade protection. Read-only job permissions are the default.
 - The bootstrap checks validate repository content and the validation tools on

README.md

@@ -33,7 +33,7 @@ migration requirements, and acceptance criteria.
 
 ## Development
 
-Use a feature branch from `develop` and open a PR back to `develop`. `main`
+Use a feature branch from `develop` and rebase merge its PR into `develop`. `main`
 remains locked between authorized releases. See [AGENTS.md](AGENTS.md) and
 [the development and release workflow](docs/RELEASING.md).
 

docs/RELEASING.md

@@ -5,11 +5,10 @@
 This repository contains project scaffolding. It has no standalone application,
 package, release version, or Omarchy marketplace submission yet.
 
-The initial CI/workflow setup is a one-time bootstrap: merge the setup PR into
-`develop` after both checks pass, then merge a bootstrap PR from `develop` into
-`main` after both checks pass. Lock `main` immediately afterwards. This is not
-an application release and creates no release tag. Future promotion requires
-an explicit release instruction from the owner.
+The initial CI/workflow bootstrap is complete. Its history was subsequently
+linearized at the owner's request. This is not an application release and
+creates no release tag. Future promotion requires an explicit release
+instruction; repairing existing history is governed separately below.
 
 ## Development
 
@@ -20,15 +19,39 @@ an explicit release instruction from the owner.
    `python3 -m unittest discover -s tests -v`.
 3. Push the feature branch and open a PR targeting `develop`.
 4. Wait for `test` and `windows-check` on the current PR revision. Resolve
-   conversations and update from the base branch when GitHub requires it.
-5. Merge through the PR without admin bypass. Keep working from `develop`.
+   conversations and rebase onto the base branch when GitHub requires it.
+5. Rebase merge through the PR using its checked head SHA, without admin bypass.
+   Do not use merge commits or squash merging. Keep working from `develop`.
 
 Both integration branches require up-to-date checks, PRs, resolved
-conversations, and administrator enforcement. They prohibit force pushes and
-deletion. This is a solo-maintainer workflow: zero additional approvals are
+conversations, administrator enforcement, and linear history. Force pushes are
+enabled for history rewriting; branch deletion remains prohibited. This is a
+solo-maintainer workflow: zero additional approvals are
 required. `main` has an additional lock between releases and remains the default.
 Tags matching `v*` cannot be updated or deleted, including by administrators.
 
+## History rewriting
+
+History may be rewritten for rebasing and cleanup; do not rewrite unrelated
+work or published version tags. An explicit owner instruction is required to
+unlock or rewrite `main` outside a release.
+
+1. Fetch current refs, inspect local status and the affected history, and record
+   the expected full remote SHA. Do not create backup bundles unless requested.
+2. Prepare linear replacement commits and verify the intended tree changes.
+   Run local checks and obtain passing GitHub checks for the replacement SHA
+   before updating an integration branch.
+3. Use `--force-with-lease=refs/heads/BRANCH:EXPECTED_SHA`, never plain force.
+   If the lease fails, stop and reconcile new remote work; do not replace the
+   expected SHA blindly.
+4. Required checks and linear history remain enforced. If GitHub's PR rule
+   blocks an explicitly authorized ref repair, temporarily lift only that PR
+   requirement on the affected branch for the repair, then restore it in a
+   `finally` block. Do not use this exception for ordinary feature delivery.
+   Unlock `main` only for the authorized operation and relock it immediately.
+5. Read back the branch SHA and protections, verify push CI on the resulting
+   revision, and update the local checkout without discarding uncommitted work.
+
 ## What CI proves today
 
 `test` runs on Ubuntu and `windows-check` runs on a native Windows runner.
@@ -52,14 +75,14 @@ real packaging; there are currently no installable artifacts to publish.
 1. Obtain an explicit release instruction. Prepare the version, changelog,
    package contents, dependency declarations, installation/migration/removal
    instructions, and recovery validation on a feature branch from `develop`.
-2. Pass relevant local suites and GitHub checks. Merge into `develop`, then open
+2. Pass relevant local suites and GitHub checks. Rebase merge into `develop`, then open
    a release PR from `develop` into `main`. Do not include unfinished features.
 3. Wait for all required checks on the release PR's current revision. Leave
    `main` locked during preparation and review.
 4. For the authorized promotion only, unlock `main` while retaining required
-   PRs, checks, and administrator enforcement. Merge the release PR once and
+   PRs, checks, and administrator enforcement. Rebase merge the release PR once and
    immediately lock `main` again. If promotion fails, restore the lock before
-   other work. Read back the protection settings and record the full merge SHA.
+   other work. Read back the protection settings and record the resulting full SHA.
 5. Verify the push checks on that exact `main` SHA. Create a new version tag
    pointing to it and publish the reviewed artifacts and release notes. Never
    move an existing release tag.