diff --git a/README.md b/README.md index 63ea919..4c8c7bf 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,29 @@ Canonical site: https://proteus.askaconsult.com/ The canonical site is the public documentation for Protean Kit. For the service listing, see the canonical site. +## What's new in this release (1.8.0) + +### What + +Add three choreography rules plus the README, CHANGELOG, and site entries that carry them: + +1. **Fresh-branch requirement** (choreography/open-source-contribution.md) — every contribution branch must be created from a fresh fetch of the target repository's default branch. +2. **Commit serialization boundary** (choreography/orchestration.md) — stage and commit must be serialized for a declared file set. +3. **Stale-tree hazard worked example** (choreography/self-improving-flywheel.md) — encodes the same incident as rule 1. +4. **Session-start router** (templates/personas/SOUL.md.tmpl) — at session start, read the orchestration contract once and apply it before the first dispatch. +5. **Mirror forks rule** (choreography/self-improving-flywheel.md) — when one repository has mirror forks, one change must reach every mirror with consistent author identity and file set. +6. **Peer-team cross-review** (choreography/orchestration.md) — a second team may review a staged PR via a written handoff message carried by the operator. + +These rules prevent PRs that revert or duplicate existing work due to stale branches, enable multi-mirror consistency, and provide a clean cross-team review procedure. The README, CHANGELOG, and index.html surfaces carry the change. + +### Why + +During an orchestration test, a stale branch 14 commits behind origin/main was used as a PR base, which would have deleted content already shipped on main. A stale base produces a PR that reverts or duplicates existing work. + +### Evidence + +[VERIFIED — internal operating record] Grounded in the team's shared doctrine and dated session history. + ## What problem does it solve? One AI agent can lose track, skip steps, or claim work is done when it isn't. Protean Kit sets up several agents with separate jobs — planner, builder, checker — and rules so that: diff --git a/choreography/open-source-contribution.md b/choreography/open-source-contribution.md index 91dcf5f..f36f285 100644 --- a/choreography/open-source-contribution.md +++ b/choreography/open-source-contribution.md @@ -46,6 +46,20 @@ smallest plausible fix. `[REQUIRED — repository evidence]` +## Branch freshness requirement + +Every contribution branch must be created from a fresh fetch of the target +repository's default branch. An agent created a PR branch from a local branch +that was 14 commits behind origin/main. The diff would have deleted content +that had already shipped on main. A stale base produces a PR that reverts or +duplicates existing work. Before creating a contribution branch, fetch the +target repository's default branch and create the branch from the fetched head, +not from a local branch that may be stale. This is enforced in the `The four +steps` > `1. Identify` step, which already requires checking "the current +upstream state." + +`[VERIFIED — internal operating record]` + ### 2. Draft Choose a pull request or an issue by using the project's own contribution model: diff --git a/choreography/self-improving-flywheel.md b/choreography/self-improving-flywheel.md index 874aec3..596aaeb 100644 --- a/choreography/self-improving-flywheel.md +++ b/choreography/self-improving-flywheel.md @@ -110,6 +110,36 @@ proposal. It does not enter the shared layer. `[VERIFIED — internal operating record, 2026-09-15]` +### 4. Stale-tree hazard + +- **Incident:** A stale branch was used as a PR base. An agent created a PR + branch from a local branch that was 14 commits behind origin/main. The diff + would have deleted content that had already shipped on main. +- **Root cause:** No rule required verifying branch freshness before creating a + PR branch. +- **Smallest rule:** Before creating a contribution branch, fetch the target + repository's default branch and create the branch from the fetched head, not + from a local branch that may be stale. +- **Canonical home:** The shared contribution contract (choreography/open-source-contribution.md). +- **Verification:** A different member checks that the PR base commit matches + the fetched head of the target default branch. +- **Re-test:** The next contribution PR must show a base commit that is at or + ahead of the target repository's default branch head at the time of branch + creation. + +`[VERIFIED — internal operating record, 2026-09-15]` + +### 5. Mirror forks + +- **Incident:** When a repository has mirror forks, a change to one mirror does not automatically propagate to the others. +- **Root cause:** No rule required that a change reach every mirror with consistent author identity and file set. +- **Smallest rule:** When one repository has mirror forks, one change must reach every mirror; extract the diff once, apply it to each mirror, rebuild each commit with its own file set and its own author identity, and confirm the rebuilt trees are identical across mirrors. +- **Canonical home:** The shared choreography contract, where multi-repo synchronization rules are inherited by every role. +- **Verification:** A different member checks that each mirror has the same tree and the commit author identity matches the mirror's convention. +- **Re-test:** The next change applied to mirrors confirms identical trees across all mirrors. + +`[VERIFIED — internal operating record, 2026-09-15]` + ## Operating record The flywheel is complete only when the rule is canonical, independently