Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
14 changes: 14 additions & 0 deletions choreography/open-source-contribution.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
30 changes: 30 additions & 0 deletions choreography/self-improving-flywheel.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down