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
49 changes: 5 additions & 44 deletions .claude/skills/branching-strategy/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,49 +5,10 @@ description: Use when creating a new branch or git worktree for a feature, bugfi

# Branching Strategy

## Overview
Follow **Creating Work Branches** and **Branch Roles** in the root `AGENTS.md`. They are the only source for bases, branch names and merge targets.

New work branches start from a user-selected `upstream/XX-dev` integration branch. The current checkout and `main` are not implicit bases. Resolve available lines from fetched refs; the user chooses the base.
The usual case after `git fetch origin --prune`:

`main` is the release line. `upstream/XX-dev` branches are the versioned dev/integration lines where feature and bugfix work lands.

## Workflow

1. **Refresh and discover bases.** Remote-tracking refs go stale here; fetch first:
```bash
git fetch origin --prune
git branch -a --list '*upstream/*' # upstream/XX-dev lines
git branch -a --list '*feat/*' --list '*fix/*' # active working branches
```
If remote state is in doubt, cross-check with `gh api repos/<org>/<repo>/branches --jq '.[].name'`.

2. **Ask the user which base to start from** (AskUserQuestion). Always ask, even when only one `upstream/XX-dev` exists. Offer as choices:
- Each `upstream/XX-dev` branch — recommend the newest version.
- "An existing working branch" — for work that depends on another in-flight branch.

3. **Create the branch** (name it `feat/<slug>` or `fix/<slug>`, matching existing repo conventions):
```bash
git checkout -b fix/<slug> <chosen-base>
# or isolated:
git worktree add ../<repo>-<slug> -b feat/<slug> <chosen-base>
```

4. **Dependent base? Flag the merge-back immediately.** If the base is a working branch rather than `upstream/XX-dev`, tell the user in your response, and repeat it when the work is ready to merge:
> ⚠️ This branch is based on `<parent-branch>`, not `upstream/XX-dev`. It must merge back only after (or together with) its parent, and merging into `upstream/XX-dev` may conflict with the parent's changes. Rebase onto the parent if it moves.

5. Don't push or set an upstream tracking branch until the user asks.

## Quick Reference

| Situation | Base | Extra step |
|---|---|---|
| Feature / bugfix | `upstream/XX-dev` chosen by user | — |
| Work depending on an in-flight branch | that working branch, if user confirms | Merge-back conflict warning (step 4) |
| Base unclear / user unavailable | stop and ask | Never guess |

## Common Mistakes

- **Branching from current HEAD or `main` without asking** — the checked-out branch is not evidence of the right base. List the `upstream/*-dev` lines and ask.
- **"Only one dev branch exists, so no need to ask"** — still ask; the user may want a dependent working branch as base, or a new dev line may be pending.
- **Silent dependent branch** — creating a branch off another feature branch without stating the merge-back risk leaves the user to discover conflicts at PR time.
- **Trusting stale remote refs** — always `git fetch origin --prune` before listing candidate bases.
```bash
git worktree add ../<repo>-<slug> -b feat/<slug> origin/develop
```
10 changes: 1 addition & 9 deletions .cursor/rules/branching-strategy.mdc
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,4 @@ alwaysApply: false

# Branching Strategy

New work branches start from an `upstream/XX-dev` integration branch (e.g. `upstream/0.6-dev`) — never silently from `main` or from whatever branch is checked out. The user chooses the base; never pick it yourself.

1. `git fetch origin --prune`, then list `upstream/*-dev` lines and active `feat/*`/`fix/*` branches.
2. Ask the user which base to start from, offering each `upstream/XX-dev` (newest recommended) plus "an existing working branch" for work that depends on another in-flight branch. Ask even when only one dev line exists.
3. Create the branch as `feat/<slug>` or `fix/<slug>` from the chosen base.
4. If the base is a working branch rather than `upstream/XX-dev`, warn immediately: it must merge back only after (or together with) its parent, merging into `upstream/XX-dev` may conflict with the parent's changes, and it needs a rebase if the parent moves. Repeat the warning at merge time.
5. Do not push or set upstream tracking until asked.

Canonical workflow: @.claude/skills/branching-strategy/SKILL.md
Follow **Creating Work Branches** and **Branch Roles** in @AGENTS.md. They are the only source for bases, branch names and merge targets.
130 changes: 77 additions & 53 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,24 +7,28 @@ are the only place for work status, acceptance criteria and proof.
## Work Tracking And Acceptance

- GitHub issues own the work queue. In each lane, take the lowest-numbered open
task whose dependencies are satisfied and which has no active blocker. Keep
at most one task issue In progress per lane. Parent issues group the lane;
task in the current weekly milestone whose dependencies are satisfied and
which has no active blocker. Keep at most one task issue In progress per
lane. Parent issues group the lane;
they do not authorize a second active task. User messages approve, redirect
or reorder work; they do not create a parallel task list.
- Close a task only when its Done means is proven and its PR has the required
reviews and is merged. Until then, keep verified work open in QA / Review.
Take the next unblocked task in that lane; starting it does not complete its
predecessor. Keep blocked work open with its blocker in the issue.
- While CI runs after a push, start or continue the next eligible issue in the
other lane. Keep the one-active-task limit in each lane. Read CI results when
they finish; do not watch or poll CI. If both lanes are blocked, record the
blockers in their issues.
- Follow CI and installed journeys that you start to completion in the same
turn. While they run, continue eligible work in the other lane and keep the
one-active-task limit. Inspect the completed result, repair failures, and
verify the new candidate before handing back. An external blocker belongs
in the owning issue.
- Run at most one heavy local build on this Mac at a time. Workers agree which
issue owns that build before starting it. CI builds do not count toward this
local limit. Continue reviews, source work or other light checks in parallel.
- Update the owning GitHub issue before reporting progress. State what changed,
link the PR, and record the exact candidate, checks, results and remaining
work. The report names the issue, PR, proof and next issue.
- Update the owning GitHub issue before reporting a state change. Routine
status notes and check-ins link the PR, CI run and review, then state the
result and remaining work. Keep exact source, tree and artifact identities
in installed-binary and release receipts, and in the private lifecycle
inventory. A routine status note uses those links instead of copied hashes.
- Keep one work record. Do not create briefings, plans, gists or notes files.
Existing `state.md`, `TASKS.md` and dated audits are historical references;
move useful open work to its issue instead of maintaining a parallel queue.
Expand Down Expand Up @@ -58,50 +62,51 @@ are the only place for work status, acceptance criteria and proof.

## Branch Roles

- `main` is the stable source line.
- `upstream/<version>-dev` branches are development integration lines. The
owning GitHub issue records the approved task base; fetched refs verify it.
This replaces the old rule to choose the active line from `state.md` and fetched refs.
- `main` is the release line. It changes only through the weekly release PR.
- `develop` is the integration line. Task PRs merge into it when their checks
and reviews pass (see Review And Commit Discipline).
- Feature and fix branches remain unpublished working lines until they are
explicitly pushed for review.
- Do not assume a `review/*` or `live` ref exists. Identify the exact public
review or deployed commit from fetched refs and target-host evidence before
making either claim.
- Treat any other local branch or target-host checkout as evidence only after
reporting its exact branch, commit, tree id, dirty status, and verification
command.
- Verify the exact branch, commit, tree id, dirty status and command before
treating a local branch or target-host checkout as evidence. Keep these
identities in the lifecycle inventory or the installed-artifact receipt;
routine check-ins link the related PR, CI run and review.
- Always report remote divergence. A local branch being green is not the same as
`elacity/<branch>` being up to date.

## Creating Work Branches

Every 0.7.1 task branch uses [feat/0.7.1-models](https://github.com/Elacity/elastos-runtime/tree/feat/0.7.1-models) as its base and PR target unless
the owning issue specifies another base. This is standing approval; do not ask
for each task. Fetch the current base before branching and record it in the issue.
Tasks that use this default base depend on the models branch and merge back into
it. Exceptions follow the base and target recorded in their issue. If the base
moves, check compatibility before merging; history rewrite still needs approval.
This standing approval takes precedence over the branching skill's per-task
base question for 0.7.1.

For other work without an approved issue base, use a user-selected
`upstream/XX-dev` integration branch. The current checkout and `main` are not
implicit bases:

- Run `git fetch origin --prune`, then list `upstream/*-dev` lines and active
`feat/*`/`fix/*` branches before proposing bases.
- Ask the user which base to start from, offering each `upstream/XX-dev`
(newest recommended) plus "an existing working branch" for work that depends
on another in-flight branch. Ask even when only one dev line exists.
- If the chosen base is a working branch rather than `upstream/XX-dev`, warn
immediately: the new branch must merge back only after (or together with)
its parent, merging it into `upstream/XX-dev` may conflict with the parent's
changes, and it needs a rebase if the parent moves.
- Name branches `feat/<slug>` or `fix/<slug>`. Pushes and upstream tracking
follow the Push Approval Levels below.
Every task branch uses [develop](https://github.com/Elacity/elastos-runtime/tree/develop)
as its base and PR target unless the owning issue names another base. This is
standing approval; do not ask for each task. Fetch the current base before
branching. If the base moves, check compatibility before merging; history
rewrite still needs approval. A branch that depends on another in-flight branch
says so in its PR and merges after its parent. Name branches `feat/<slug>` or
`fix/<slug>`. Pushes and upstream tracking follow the Push Approval Levels below.

Canonical workflow: [.claude/skills/branching-strategy/SKILL.md](.claude/skills/branching-strategy/SKILL.md).

## Weekly Releases

- Each weekly release has a milestone `0.7.N`. Its scope is fixed on the
Wednesday before the release; work that misses it moves to the next milestone.
- On Tuesday the candidate is cut from `develop` as `release/0.7.N` with the
version bump and changelog, and opened as a PR to `main`.
- Three people confirm the candidate before the tag. Sasha reviews the visible
changes (CI screenshots and a short look) on his Wednesday. `irzhywau`
approves the release PR. Anders runs the ten-minute journey on his Mac: a
fresh install (an update from the previous weekly release once the signed
update tasks UP-01 to UP-03 are merged), sign in, one local AI reply, one chat
message and one Browser page. A failed journey or a visible regression holds
the tag for that week.
- On Wednesday the PR merges, `v0.7.N` is tagged on the merge commit, and `main`
merges back into `develop`.
- 0.8.0 is the weekly release in which every result in the 0.8.0 milestone meets
its Done means.

## Branch Lifecycle

Retire a branch or close a PR only with its owner's agreement. A green check,
Expand Down Expand Up @@ -210,14 +215,12 @@ target before acting.
- **No approval needed:** fast-forward pushes to the branch of the active task
or its existing draft PR; opening draft PRs; rerunning checks; reading logs.
Report what was pushed, including the remote, branch, commits and check results.
- **Standing task-merge permission:** merge a task PR only into the repository
and target branch explicitly approved by the user for that task.
Check that approval before merging. A change to the approved target requires
explicit user approval. The current candidate must pass all required checks,
independent review must be complete, required human reviews must approve the
candidate, all findings must be resolved, and its dependencies must be integrated.
Check compatibility with the current base and report the PR, source and merge
commits, review and checks. Use a normal merge; history rewrite needs approval.
- **Standing task-merge permission:** merge your task PR into `develop`, or
into the user-approved base named in its issue, when all current checks pass,
the independent reviews below pass, findings are resolved, dependencies are
integrated, and any explicit human acceptance gate passes. Check current-base
compatibility and report links to the merged PR, CI run and reviews. Use a
normal merge; history rewrite needs approval.
- **Standing test-key permission:** create and use disposable keys and signatures
for a named, isolated test fixture. Keep its trust store separate from real
Homes and production keys. Record its owner and cleanup condition; keep private
Expand All @@ -227,7 +230,10 @@ target before acting.
keys; changes on the seed or existing installed Homes; deleting branches;
other secrets and credentials.

Signing runs outside CI. Fork PRs and publication jobs use GitHub-hosted runners.
The operator runs production signing with Anders's approval. Named isolated
fixtures may generate disposable keys and signatures in CI; their trust stays
separate from real Homes and production keys. Fork PRs and publication jobs use
GitHub-hosted runners.

These levels replace blanket push-approval requirements. Verification and the
agreed publication scope still apply. Keep unrelated work and private operational
Expand All @@ -251,10 +257,22 @@ capsules, provider config, and `components.json`.
- Keep review requests off draft PRs. When a PR leaves draft, request the
required reviewers on GitHub yourself and name them in the report. Keep an
existing request instead of sending a duplicate.
- For a PR authored by Anders that touches signing, update checks, Inbox
approvals, keys, sandboxing or seed publishing, name `irzhywau` as a required
human reviewer. Also name the feature owner when the task requires that review.
Independent agent review and required human review are separate evidence.
- Each task change needs one independent development review marked PASS.
Security code, including gateway, auth, provider launchers, confinement,
signing, publish/update, install.sh and workflows, also needs a posted
`Independent adversarial review ... VERDICT: PASS` from a different model
family than its author. Codex authors run `elastos-pr-review <PR>` themselves
and verify that the posted verdict covers the current candidate.
- Agents merge their own task PRs after the current checks and reviews pass.
Keep explicit human acceptance gates recorded in the owning issue. Request
`irzhywau` for security follow-up: he reviews merged security task PRs, and a
finding goes into an existing issue or a revert when it reopens a hole.
When he authors a security task PR, Anders conducts the follow-up review.
Weekly release PRs still need his approval before merge and tag; when he is
the author, Anders reviews. Also request the feature owner when required.
- Use one development review round per coherent change. Resolve findings in
that round and fix their cause before requesting the current verdict. Scope
decisions belong to Anders. Ask before adding new diagnostic tooling.
- Keep commits authority-bound and reviewable: one coherent concern per commit,
with its own verification commands.
- Preserve commit history by default. Ask before amending, squashing, rebasing
Expand Down Expand Up @@ -312,6 +330,12 @@ path, installed artifact path, SHA-256 of the built and installed artifact,
restart or stale-process cleanup performed, and the live localhost proof command
and result.

Prove installed behavior on the CI install jobs (GitHub-hosted Linux x86-64,
Linux ARM64 and macOS machines) when they cover the journey, and link that CI
run as the proof. Otherwise use the installed-proof steps above. The Jetson is
checked on the weekly candidate. A PR that changes what users see links the CI
screenshots at desktop and phone width.

## Journey Register Gate

Use [docs/audits/ElastOS-Home-Journey-Audit.xlsx](docs/audits/ElastOS-Home-Journey-Audit.xlsx)
Expand Down
24 changes: 19 additions & 5 deletions scripts/home-entropy-check.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -1853,14 +1853,28 @@ assert(
agentsContract.includes("## Public Live Deployment") &&
agentsContract.includes("## Staging Machines") &&
agentsContract.includes("## Browser Claim Discipline") &&
agentsContract.includes("`main` is the stable source line") &&
agentsContract.includes("`upstream/<version>-dev` branches are development integration lines") &&
includesNormalized(agentsContract, "the active line from `state.md` and fetched refs") &&
agentsContract.includes("## Weekly Releases") &&
agentsContract.includes("`main` is the release line") &&
agentsContract.includes("`develop` is the integration line") &&
includesNormalized(agentsContract, "Fetch the current base before branching") &&
agentsContract.includes("Do not assume a `review/*` or `live` ref exists") &&
agentsContract.includes("reporting its exact branch, commit, tree id, dirty status") &&
includesNormalized(agentsContract, "Verify the exact branch, commit, tree id, dirty status and command") &&
agentsContract.includes("Target proof must cite the exact source tree") &&
agentsContract.includes("explicit user approval before the mutation") &&
agentsContract.includes("WebRTC remote display"),
agentsContract.includes("WebRTC remote display") &&
includesNormalized(agentsContract, "Follow CI and installed journeys that you start to completion in the same turn") &&
includesNormalized(agentsContract, "status notes and check-ins link the PR, CI run and review") &&
includesNormalized(agentsContract, "Keep exact source, tree and artifact identities in installed-binary and release receipts") &&
includesNormalized(agentsContract, "Before deleting a duplicate ref, prove exact commit identity") &&
includesNormalized(agentsContract, "Before deleting a worktree, verify its status, untracked files, open files/processes, and protecting ref") &&
agentsContract.includes("VERDICT: PASS") &&
includesNormalized(agentsContract, "Each task change needs one independent development review marked PASS") &&
includesNormalized(agentsContract, "from a different model family than its author") &&
includesNormalized(agentsContract, "verify that the posted verdict covers the current candidate") &&
includesNormalized(agentsContract, "Weekly release PRs still need his approval before merge and tag; when he is the author, Anders reviews") &&
includesNormalized(agentsContract, "`irzhywau` for security follow-up: he reviews merged security task PRs") &&
includesNormalized(agentsContract, "When he authors a security task PR, Anders conducts the follow-up review") &&
agentsContract.includes("elastos-pr-review <PR>"),
"Root AGENTS.md must preserve standing branch roles, fetched-base selection, target proof, public-live approval and Browser claim discipline",
);
assert(
Expand Down
Loading