From 8eafb7737703e6bf29f60c03d5f68ff15091cba4 Mon Sep 17 00:00:00 2001 From: Fabian Hamm Date: Wed, 9 Sep 2026 19:37:40 +0200 Subject: [PATCH] docs: give the Port agent an `Each iteration` section (it had none) `decoder-loop.md` has had `## Each iteration` since 2026-09-04, ending in 7. Commit, `push-work`, open the PR, label the issue `state/needs-human`, and stop. `port-loop.md` has never had that section at all. It states the rules -- "you cannot close your own work", "you move an item to state/needs-human", work reaches main "through pull requests" -- but nowhere gives the STEPS that carry them out. The Port agent was told the rule and never the procedure. Two steps were missing entirely, and both are Phase 7 check items: * READ YOUR NOTIFICATIONS first. They are polled and nothing pushes them, so an agent that skips this never receives anything addressed to it -- and the symptom is silence, not an error. That is GITEA-SETUP.md Phase 7 check 1. * OPEN THE PR AND SET THE LABEL. That is Phase 7 check 2. The second carries a trap worth naming in the brief rather than in a runbook: `docker/port/bin/push-work` ONLY PUSHES. Verified by reading it -- no /pulls call, no `Closes #`, no label; its refusals (no main, no force-push) are intact. `propose-work`, which would do all three, is still unbuilt -- GITEA-SETUP.md's own words are "the other two thirds being manual is how they get skipped". The capability is there (`pull_request_write` and `issue_write` are both in the pinned MCP tool set), so this is an instruction gap, not a permissions one. Written to mirror the Decoder's shape while using the Port's own vocabulary -- a gate is an artifact, verify against captures rather than our renderer, state the expected number first, `authored/` entries carry a `why`, never an invented number where a measured one is pending. Found by the Pi agent while answering a Phase 7 readiness question. My own check had been decoder-only, which is why the asymmetry survived it. Refs #11 Co-Authored-By: Claude Opus 5 --- docs/agents/port-loop.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/agents/port-loop.md b/docs/agents/port-loop.md index e1c90f80..3cd25bdb 100644 --- a/docs/agents/port-loop.md +++ b/docs/agents/port-loop.md @@ -89,6 +89,39 @@ what a given instrument killed, so those re-open when it improves. Grep 5. [`TEMPORAL-VERIFICATION.md`](TEMPORAL-VERIFICATION.md) — binding on anything that moves. +## Each iteration + +The Decoder's brief has had this section since 2026-09-04; this one did not, so +the rules below were stated but the *steps* that carry them out were never +written down. Steps 1 and 8 are the ones that were missing entirely. + +1. **Read your notifications**, then `git fetch origin && git merge origin/main`. + Notifications are **polled — nothing pushes them.** If you skip this, nothing + addressed to you ever arrives, and it looks like silence rather than an error. +2. **Pick one item** — the highest-priority `state/approved` issue that is yours. + Mid-item? Continue it. +3. **Build the smallest thing that reaches a gate.** A gate is an **artifact**, + never "it compiles". +4. **Verify against captures of the real game, not against our renderer**, and + **state the expected number before you measure it.** Where a capture and + `sylpheed-cli screen render` disagree, say which is wrong rather than tuning + until they agree. +5. **Classify every value you author.** Exactly one of: **decoded** (a spec in + `docs/re/`, cited by path) · **measured** (the Decoder measured it off the + running game, with the capture) · **authored** (you chose it — it goes in + `authored/` with its `why`, and it is *not* a measurement). Never a fourth + thing, and never an invented number where a measured one is pending. +6. **Refute something.** Each iteration, attempt to refute one claim — another + agent's, or one of your own from a previous iteration — and record the + attempt whether or not it survived. +7. **Write it down** in `docs/port/`, and record the `HANDOFF.md` sha you built + against. +8. **Commit, `push-work`, open the PR**, label the issue `state/needs-human`, and + **stop.** One unit per iteration; do not stack a second on an unverified + first. ⚠️ `push-work` **only pushes** — it does not open the PR and does not + set the label. Those are two separate MCP calls (`pull_request_write`, + `issue_write`), and they are the two most commonly skipped steps in this list. + ## The wall The Godot project **never reads a disc format**. No IPFB, RATC, T8aD, XMA or WMV.