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
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Read [execution-policy.md](execution-policy.md) and [delivery-procedure.md](deli

1. **Strictly serial.**
- One `active` task; `python tools/plan.py next` names it.
- One delegated worker or reviewer at a time, Opus 5.5 only, never Haiku.
- One delegated worker or reviewer at a time, without a required provider or model.
- No build slot, no claims, no leases.
2. **Never resume history.** Nothing from Plan-Parallel, the old launcher or old claims is resumed ([history/legacy-disposition.md](history/legacy-disposition.md)).
3. **Worktrees.** Work in worktrees (`<repo>/.worktree/<key>`), never in main checkouts. This applies to the Plan too: `plan/<topic>` branches in `.worktree/`.
Expand Down Expand Up @@ -79,7 +79,7 @@ Read [execution-policy.md](execution-policy.md) and [delivery-procedure.md](deli
- The coordinator does not change repository security settings. The first exception is the required status checks of the conditional CI ([AD-0016](https://github.com/ArcForges/ArcForges-Design/blob/main/docs/decisions/AD-0016-local-first-verification.md) §2), which the coordinator may change only as the user authorized on 2026-10-16: "If existing required checks must be adjusted to support this conditional workflow, make the smallest appropriate changes." The second is the `main` rulesets that require the host statuses (AD-0020 §6), which the user authorized on 2026-10-22 for that migration. Neither is ever changed to get a PR merged.
- Read hosted CI (external PRs) with the PR tools; never poll it.
- Never enable auto-merge unless the user asks.
9. **Commits and PRs.** Commit messages end with `Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>`. PR bodies end with `🤖 Generated with [Claude Code](https://claude.com/claude-code)`.
9. **Commits and PRs.** Any commit co-author trailer or PR footer must identify the actual contributors and tools used.
10. **Run gate and continuous execution.** No implementation starts until the user authorizes it with the execution prompt ([execution-prompt.md](execution-prompt.md)) and a pasted range of `sequence.md` steps. The range is the authorized scope and is recorded as a ledger `note` (execution policy §1.5). Deliver the eligible tasks of the range one at a time, without asking to continue, and never start a task outside the range.
11. **Stop points.** Stop and ask the user before outward-facing publication, when the authorized range is complete, when no eligible task remains in it, when a task outside the range is active, when no confirmed Opus 5.5 reviewer is available, when a decision only the user can make is required, or when the user says stop. When a human prerequisite (H-*) whose **Blocks** column in the acceptance register names a task is missing, set the task `blocked` with that ID (`plan.py set-state <id> blocked --blocked-by H-xx --reason ...`), tell the user exactly what is needed, and continue with the next eligible task of the range; blocked tasks and their dependents are skipped. Prerequisites that block only `complete`, or nothing, never block the task. Production prerequisites block only AF-PROD-01, because Cloud and Web tasks deploy dark.
11. **Stop points.** Stop and ask the user before outward-facing publication, when the authorized range is complete, when no eligible task remains in it, when a task outside the range is active, when no independent reviewer is available, when a decision only the user can make is required, or when the user says stop. When a human prerequisite (H-*) whose **Blocks** column in the acceptance register names a task is missing, set the task `blocked` with that ID (`plan.py set-state <id> blocked --blocked-by H-xx --reason ...`), tell the user exactly what is needed, and continue with the next eligible task of the range; blocked tasks and their dependents are skipped. Prerequisites that block only `complete`, or nothing, never block the task. Production prerequisites block only AF-PROD-01, because Cloud and Web tasks deploy dark.
12. **Roadmap.** [roadmap.md](roadmap.md) is the only backlog for work that is not committed delivery. Never implement a roadmap item; promotion to tasks follows roadmap.md §4.
4 changes: 2 additions & 2 deletions delivery-procedure.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,8 @@ Run exactly what the task's `verification.author` names: the affected suites whi

## 4. Review

1. The coordinator pushes the branch and opens the PR, then runs `python eng/verify.py run-and-report` on each host for the head ([AD-0020](https://github.com/ArcForges/ArcForges-Design/blob/main/docs/decisions/AD-0020-post-push-verification-and-required-checks.md); `AGENTS.md` rule 6). The hosts report `arcforges/windows` and `arcforges/linux` on the commit, which the `main` ruleset requires. A failure goes back to the author (or the coordinator fixes a coordinator-side cause), and the fixed branch is pushed and verified again. A status is never posted by hand (policy §3). The PR body ends with `🤖 Generated with [Claude Code](https://claude.com/claude-code)`, and commits end with `Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>`.
2. **One independent reviewer** (Opus 5.5, a fresh session) reviews the exact head:
1. The coordinator pushes the branch and opens the PR, then runs `python eng/verify.py run-and-report` on each host for the head ([AD-0020](https://github.com/ArcForges/ArcForges-Design/blob/main/docs/decisions/AD-0020-post-push-verification-and-required-checks.md); `AGENTS.md` rule 6). The hosts report `arcforges/windows` and `arcforges/linux` on the commit, which the `main` ruleset requires. A failure goes back to the author (or the coordinator fixes a coordinator-side cause), and the fixed branch is pushed and verified again. A status is never posted by hand (policy §3). Any commit co-author trailer or PR footer must identify the actual contributors and tools used.
2. **One independent reviewer** (a fresh session) reviews the exact head:
- the full diff against the design references and acceptance criteria;
- distinct checks only (policy §3).

Expand Down
6 changes: 1 addition & 5 deletions entry-prompts.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Use [execution-prompt.md](execution-prompt.md), the self-contained coordinator p

> You are the ArcForges delivery coordinator. Read `C:\MyFile\Projects\ArcForges\Plan\AGENTS.md`, `execution-policy.md` and `delivery-procedure.md`. Deliver only the tasks of the range I pasted, in sequence order, after recording my authorization as a ledger note. If a task is `active`, resume it from its last ledger note. `blocked` tasks wait for their named prerequisites, and their dependents are skipped.
>
> Work strictly serially. You may delegate to one Opus 5.5 worker at a time (never Haiku). Then use one independent Opus 5.5 reviewer, after the author.
> Work strictly serially. You may delegate to one available worker at a time, without a required provider or model. Then use one independent reviewer, after the author.
>
> Use git worktrees, never main checkouts. Only you push, verify each pushed head on both hosts with `python eng/verify.py run-and-report` (Plan `AGENTS.md` rule 6; never post a status by hand or change a ruleset to merge), open PRs, post review records, read hosted CI of external PRs through the PR tools (never poll), merge at the reviewed head, and record the result in the graph and ledger.
>
Expand All @@ -18,8 +18,6 @@ Use [execution-prompt.md](execution-prompt.md), the self-contained coordinator p

## P-2 Worker: implement one task (delegated)

> Begin your reply with your model ID on its own line.
>
> Implement Plan task `<ID>` (`python tools/plan.py show <ID>` in `C:\MyFile\Projects\ArcForges\Plan`) in the worktree(s) `<paths>` on branch `task/<id>`. Stay inside the task's write scope.
>
> Read its design references in ArcForges-Design. Write the tests named in its verification, using fakes only where `fakes_allowed` lists them. While iterating, run the affected suites (the repository's `AGENTS.md`, Efficient execution). Run the author verification and record the exact commands and results in `PR-BODY.md` at the worktree root. Never commit `PR-BODY.md`; the coordinator uses it as the PR body.
Expand All @@ -30,8 +28,6 @@ Use [execution-prompt.md](execution-prompt.md), the self-contained coordinator p

## P-3 Reviewer: independent exact-head review

> Begin your reply with your model ID on its own line.
>
> Review Plan task `<ID>` at head `<SHA>` in `<worktree>`.
> 1. Read the complete diff against main, the task record and its design references.
> 2. Check every acceptance criterion and requirement listed, and the conventions of the repository's `AGENTS.md`.
Expand Down
4 changes: 2 additions & 2 deletions execution-policy.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Authority: ArcForges-Design [AD-0014](https://github.com/ArcForges/ArcForges-Des
2. The next task to start is the first `planned` task **of the authorized range** (§1.5) in serial order whose dependencies are `delivered`, `complete` or `superseded`. The order in the graph is the order of work. Do not reorder, skip or start tasks early. A task whose dependency lies outside the range and is not delivered is not eligible; the coordinator reports it and never implements the dependency.
- `depends_on` lists only **real** dependencies (a task needs the other's delivered code, contracts or services). The serial order is the file order, not a dependency chain, so one blocked task holds back only the tasks that really need it.
3. **Delegation.**
- A coordinator session may delegate to **one** worker or reviewer at a time, using **Opus 5.5** only, confirmed by the model ID the delegate reports first. Never Haiku. Without a confirmed Opus 5.5 reviewer, a task is not merged, and the coordinator stops and reports it.
- A coordinator session may delegate to **one** worker or reviewer at a time. Use available agents without a required provider, model, or separate client login. The reviewer must be independent of the author. Without an independent reviewer, a task is not merged, and the coordinator stops and reports it.
- No parallel research, implementation or review workstreams.
- A delegate works only in its task's worktree and never pushes, posts, merges or deploys. The coordinator does those (§4).
4. **No build slot.** There is no workstation lock and no "retry for a slot". Long checks run once, in the background when practical, and their results are read rather than polled in loops.
Expand All @@ -17,7 +17,7 @@ Authority: ArcForges-Design [AD-0014](https://github.com/ArcForges/ArcForges-Des
- The range's scope is the Task column of the pasted rows; IDs in *Depends on* are prerequisites, never scope. The coordinator records the authorization as a ledger note that lists every task ID in scope (`python tools/plan.py ledger PLAN note "Implementation authorized by the user on <date>: <ID>, <ID>, … (<count> tasks; sequence rows <first #>–<last #>)"`), merged with the first task's start record. A resumed session continues within the ID list of the latest authorization note. A session with neither a pasted range nor an unfinished authorized range only reports status (entry prompt P-5).
- Within the range, the coordinator delivers eligible tasks one after another. Serial means one task at a time, not one task per session: it reports each delivery and continues with the next eligible task in the range without asking to continue. Tasks outside the range are never started, even when `plan.py next` names one.
- A `blocked` task is skipped, not a reason to stop.
- It stops only when an outward-facing approval is needed, the authorized scope is complete, no eligible task remains, a task outside the range is active, no confirmed Opus 5.5 reviewer is available, a decision only the user can make is required, or the user says stop. It then reports where it stopped and why.
- It stops only when an outward-facing approval is needed, the authorized scope is complete, no eligible task remains, a task outside the range is active, no independent reviewer is available, a decision only the user can make is required, or the user says stop. It then reports where it stopped and why.
6. **Repairs versus new scope.** A defect in delivered code, in any repository, that prevents the current task's acceptance is repaired within that task: in its PR with a scope note when it is small and inside the task's write paths, otherwise in a separate repair PR in the owning repository, reviewed like a task and recorded in the task's evidence. A repair restores specified behaviour and adds none. Small changes outside the write paths that the task's own specified scope needs (for example solution entries, wiring, or view models for its pages) go into its PR with a scope note. A larger one first widens the task record through a reviewed Plan PR. Only behaviour that no task specifies becomes a new task proposal, which the coordinator records and reports without building it.

## 2. Task states
Expand Down
15 changes: 6 additions & 9 deletions execution-prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ Follow `delivery-procedure.md`. In short:
4. **Verify as the author.** Run what `verification.author` names, plus the affected real Windows and Linux tests. Record the exact commands and results in the PR body, mapping each acceptance criterion to its evidence.
5. **Review.**
- Push the branch and open the PR. Then run `python eng/verify.py run-and-report` on each host for the head, through its MCP server, in a worktree at the commit fetched from GitHub (Plan `AGENTS.md` rule 6). Each host reports `arcforges/windows` or `arcforges/linux` on the commit.
- One independent reviewer reviews the exact head: a fresh Opus 5.5 session using prompt P-3 from `entry-prompts.md`.
- One independent reviewer reviews the exact head: a fresh session using prompt P-3 from `entry-prompts.md`.
- Fix blocking findings. Re-review covers only the delta.
- Post the review record on the PR.
6. **Merge gate** (AD-0016).
Expand All @@ -125,12 +125,9 @@ Follow `delivery-procedure.md`. In short:
9. **Continue** with the next eligible task in your range.

**Delegation.**
- At most one delegated worker or reviewer at a time, always Opus 5.5, never Haiku. Use the worker prompt P-2 and the reviewer prompt P-3.
- **Model guarantee.** Delegate only to agents confirmed to run on Opus 5.5.
- **How to confirm.** The delegate's reply starts with its model ID (P-2 and P-3 ask for it), and the ID must identify Opus 5.5 (currently `claude-opus-5-5`).
- **Helpers.** Built-in helper agents (for example search or exploration helpers) may run on a smaller model. Never use them for task work or review.
- **Unconfirmed worker.** Do not use it; do the work yourself.
- **Unconfirmed reviewer.** A review needs a confirmed Opus 5.5 reviewer other than you. Without one, the task is not merged: record that in the ledger, report it and stop (§11).
- At most one delegated worker or reviewer at a time. Use the worker prompt P-2 and the reviewer prompt P-3.
- Use available agents without a required provider, model, or separate client login.
- The reviewer must be independent of the author. If no independent reviewer is available, record the blocker, report it and stop before merging.
- Delegates work locally in the task's worktree. Only you push, open PRs, post review records, merge and update the graph and ledger.
- The worker's `PR-BODY.md` at the worktree root is the PR body's source. Never commit it.

Expand Down Expand Up @@ -187,14 +184,14 @@ When unsure, prefer the narrower reading. Record the question in the ledger and
- Verification is MCP-first (ArcForges-Design AD-0019): the Windows leg on the owner's workstation through the Windows MCP server, the Linux leg on the Linux MCP host through the Linux MCP server (H-22). Each host fetches the pushed commit from GitHub and reports its leg as a required commit status (AD-0020). Local WSL is never used, not even as a fallback. If an MCP server is unavailable, stop and report it; the PR cannot merge without its status. Never skip a test, bypass a hook or post a status by hand. Installs on those hosts are the user's. No SSH.
- **Settings.** Never change repository security settings or account settings, except the required status checks of the conditional CI as the user authorized on 2026-10-16 (execution policy §5, AD-0016 §2), and the `main` rulesets of the post-push verification as the user authorized on 2026-10-22 (AD-0020); never to get a PR merged.
- **Accounts.** Existing access only. Never create accounts; signing custody, store accounts, payment and Firebase are human prerequisites (Plan `baseline.md` §4).
- **Attribution.** Commits end with `Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>`. PR bodies end with `🤖 Generated with [Claude Code](https://claude.com/claude-code)`.
- **Attribution.** Any commit co-author trailer or PR footer must identify the actual contributors and tools used.

## 11. When you stop

**Stop only when:**
- every task in the range is delivered or complete, or has a recorded reason it is not: blocked by a named prerequisite, a dependency outside the range not delivered, returned to planned after an unresolved failure, or superseded;
- a task outside the range is active (§5);
- no confirmed Opus 5.5 reviewer is available for a task that is ready for review (§6);
- no independent reviewer is available for a task that is ready for review (§6);
- an outward-facing step needs the user's approval;
- a decision only the user can make is required;
- or the user says stop.
Expand Down
4 changes: 2 additions & 2 deletions maintenance/2026-10-25-handoff.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,9 +97,9 @@ Notes on specific items:
- **Load during a leg.** No builds or tests on a host while its leg runs. Reviewers read only through GitHub while any leg runs.
- **Red legs.** A red leg is never rerun. Diagnose it. If the cause is unrelated to the PR, open a new item, fix it first, merge main into the blocked PR and verify again.
- **Delegation.**
- One Opus 5.5 worker per repair. It commits locally only and writes an untracked `PR-BODY.md`.
- One worker per repair, using the current execution policy without a required provider or model. It commits locally only and writes an untracked `PR-BODY.md`.
- The coordinator pushes, opens the PRs and posts the review records.
- Reviewers are independent Opus 5.5 agents.
- Reviewers are independent agents.
- **Linux user manager.** Do not kill the user's systemd user manager (PID 971443 at handoff; re-identify it by role before recovery). Do not use `pkill -f` or `daemon-reload`. After test cleanup, only `arcforges.slice` and `arcforges-test.slice` may remain among ArcForges test units.
- **Record PRs.** Branch `plan/<x>-record`, list edits, ledger notes through `tools/plan.py ledger <TASK> note`, then `plan.py validate --design <Design>`, both legs, the required independent review, merge. The policy exemption covers only task states, evidence and ledger lines written by `plan.py`; hand-edited list or handoff changes require review.
- The Windows helper for list edits is `C:\MyFile\Projects\dev\mr_list_update.py`. Prepared scripts are there too: `mr04_record.py`, `mr89_96_record.py` (already used).
Expand Down