@event4u/agent-config 16.4.0 → 17.0.0

package/dist/agent-src/contexts/execution/pr-create-branches-content.md

@@ -0,0 +1,250 @@
+# PR Create — Branch Mechanics
+
+Moved body of the `/create-pr` default flow (`commands/pr/create.md`), per
+progressive disclosure. Loaded from the command's pointer lines when a run
+takes the branch a section covers — a later push, a merge, an archival sweep,
+a scope delta, a footer strip, a red CI. The Iron-Law blocks and the default
+flow skeleton stay in the command; this file carries the explanatory prose,
+rationale, and per-branch procedure.
+
+## 2. Generate PR content
+
+The generation honors the cached content flags from step 1 (§4f):
+`detail_level` sets the Description tier (default `min`) and `screenshots`
+(capability-gated) adds frontend screenshots; a grounded JSON block for
+API-endpoint changes is always added (`/create-pr:description-only` § 4.3). Critical-info callouts
+(breaking changes / migrations / security / rollback) appear at every tier.
+
+**Preview gate** — read `commands.create_pr.preview_description` from
+`.agent-settings.yml` (default `false` when unset):
+
+- `false` (default): skip Steps 5–6 of `/create-pr:description-only` (the
+  copyable preview block + adjust loop). Use the generated title and body
+  directly in Step 3 below. This saves agent tokens by avoiding a full
+  re-render of the description in chat. The user can still edit the PR
+  body in the GitHub UI after creation.
+- `true`: run Steps 5–6 of `/create-pr:description-only` — present the
+  title and body as copyable blocks and ask for adjustments before
+  proceeding. The user reviews and adjusts the content in that step.
+
+## 2a. Scope delta — what grew, and why it was the agent's
+
+Where the run did work beyond the literal task, add a `## Scope delta` section
+to the body — one line per item, naming what grew and which row of the
+agent-owned list it matched (a necessary internal refactor · a missing test on
+a touched path · a regression on a touched path · a small dependency
+adjustment · a local API change inside defined semantics · a Boy-Scout cleanup
+that is small, local, low blast radius, testable and carries no new product
+decision). Full enumeration and the council / owner rows:
+[`scope-mechanics`](../authority/scope-mechanics.md)
+section Scope growth.
+
+`./scripts-run src/scripts/scope_growth "<one-line description>"` classifies a
+single item when the row is not obvious. `unknown` is a real verdict: growth
+nothing classifies is growth nobody decided, and it does not silently become
+agent work.
+
+A larger unrelated opportunity is **not** a scope delta. It is a follow-up
+artifact, named in the same section under *Not absorbed* with its roadmap path,
+because a mission delivering everything it met would deliver none of it.
+
+Omit the section entirely when the diff is the task and nothing grew.
+
+## 2b. Council review — explicitly excluded
+
+`/create-pr` does **not** prompt for council review, even when
+`ai_council.enabled: true`. Invoking the PR command is an explicit
+delivery action; interrupting it with a billable opt-in question is
+out of scope.
+
+Users who want a council pass on the diff run `/council diff:<base>..<head>`
+**before** `/create-pr`. Do not re-add the prompt here without an explicit
+user request.
+
+## 3a. Tool selection — single-call mandate
+
+Use the `github-api` tool **directly** with the markdown body in the
+JSON `data` field. The body is a regular JSON string — escaping is the
+tool's job, not yours.
+
+```
+github-api
+  method: POST
+  path:   /repos/{owner}/{repo}/pulls
+  data:   { "title": "...", "body": "<markdown>", "head": "<branch>",
+            "base": "main", "draft": <bool> }
+```
+
+**Hard prohibitions** (each one cost 3+ extra tool calls in past runs):
+
+- ❌ `node -e "..."` / shell heredoc hacks
+  to serialize the body or POST it.
+- ❌ `save-file PR_BODY.md` → read back → `curl -d @PR_BODY.md`.
+- ❌ `gh pr create --body-file …` shelling out when `github-api` is
+  available in this surface.
+- ❌ Splitting `title` and `body` into two API calls (create + PATCH).
+
+The body may contain any Markdown — code fences, tables, multi-line
+HTML, emoji. Do **not** preprocess, escape, or strip newlines before
+handing it to `github-api`.
+
+If the surface genuinely lacks `github-api` (rare), fall back to
+`gh pr create --title "..." --body-file <(echo -n "<body>")` as a
+**single** shell call, never the python-urllib path.
+
+## 4a. Strip attribution footers (mandatory)
+
+Some `github-api` tool surfaces append attribution server-side after
+the agent has sent a clean body. Per
+[`no-attribution-footers`](../../rules/no-attribution-footers.md), every
+PR body must be re-checked and stripped after every write.
+
+Run this strip-pass **after PR creation and after every body PATCH**:
+
+1. Re-fetch the PR body:
+   ```
+   GET /repos/{owner}/{repo}/pulls/{number}
+   ```
+2. Search the body (case-insensitive) for any of:
+   - `Generated with [Augment Code]` / `🤖 Generated with`
+   - `Pull Request opened by [Augment Code]`
+   - `Co-authored by Augment Code`
+   - Any `augmentcode.com` link the user did not ask for
+3. **No match → done.** Skip steps 4–5; the body is already clean.
+   This is the common path and **must not** spend a verify-GET.
+4. Match found → remove the footer(s) together with surrounding
+   `---` separators and trailing whitespace, then:
+   ```
+   PATCH /repos/{owner}/{repo}/pulls/{number}
+   { "body": "<cleaned body>" }
+   ```
+   Re-fetch the body **once** to verify the strip stuck. If a
+   pattern reappears (server re-injection), repeat the PATCH once;
+   if it still reappears, surface the issue to the user and stop
+   (do not enter a strip/PATCH loop).
+5. Briefly note in the reply how many footers were removed (omit
+   the line entirely when nothing was stripped — silence is the
+   expected path, not "no footers found").
+
+## 4c. Status claims — verified facts only (MANDATORY)
+
+Any statement about the PR's state — in the creation reply, after a
+conflict-resolution push, after ANY push to the PR branch — must be
+backed by fresh command output from the same reply:
+
+| Claim | Required evidence |
+|---|---|
+| Draft / ready | `gh pr view <n> --json isDraft` — quote the value |
+| CI green / red / running | `gh pr checks <n>` — report the actual fail list; a single `fail` row means FAIL, not "running" |
+| Mergeable / conflicts | `gh pr view <n> --json mergeable,mergeStateStatus` |
+
+`mergeStateStatus: BLOCKED` has several distinct causes (failing
+checks, draft state, missing reviews, branch protection). Resolving
+WHICH one requires `gh pr checks` — never guess the cause. If checks
+are still pending, say "pending" and name the pending jobs; never
+declare an outcome the output does not show.
+
+This is the [`direct-answers` Iron Law 2](../../rules/direct-answers.md)
+live-state clause applied to the PR surface: git/PR/CI state decays
+silently and is NEVER reported from memory or inference.
+
+## 4d. Settle CI before the turn ends (MANDATORY)
+
+§4c makes the REPORT honest. This makes the turn honest: a truthful
+"checks are pending" is still an unfinished job, and reporting it as the
+closing line hands the user a PR whose outcome nobody has looked at.
+Pending is a reason to wait, never a reason to stop.
+
+**Settled** means every check has reached a terminal state:
+
+```bash
+npm exec --no -- agent-config ci:settle <n>
+gh pr checks <n> --json name,state,link \
+  --jq '.[] | select(.state!="SUCCESS" and .state!="SKIPPED") | "\(.state)  \(.name)  \(.link)"'
+```
+
+`ci_settle` is the one waiter for this condition, never a hand-written
+`gh pr checks` loop, and it is never piped — its last output line is the
+verdict. Exit 0: settled green for the named head. Exit 1: settled with a
+failed check, listed by the second command — go to **On red**. Exit 2: not a
+verdict (no settle within its budget, `gh` unreadable, or the PR merged, closed
+or head-diverged); say that rather than reporting a result.
+
+Run the wait as a BACKGROUND command so the turn resumes on its own when
+the verdict lands. A foreground sleep-poll chain is blocked, and burning
+turns on `gh pr checks` every minute is the tool-loop
+[`token-efficiency`](../../rules/token-efficiency.md) forbids.
+
+**On red:**
+
+1. **Verify it is yours before fixing it.** Check `origin/main` for the same
+   failure and whether any of your files appear in the failing gate's inputs
+   (`git diff origin/main --stat -- <path>`). A pre-existing trunk failure is
+   reported, not silently adopted — and not silently ignored either.
+2. **Get the real log, do not infer.** `gh run view --job <id> --log-failed`.
+   Logs are unavailable until the whole run completes; a local repro is often
+   faster but can differ from CI (a developer checkout carries settings and
+   generated trees a clean runner does not — see the `SCOPE_GUARD_BYPASS` and
+   untracked-`dist/` cases). When local and CI disagree, CI is authoritative.
+3. **Fix, then re-verify locally** with the narrowest command that proves the
+   target green.
+4. **Bounded by the `execution.fix_loop_max` budget (default 10) and its
+   ladder, per failing target** ([`autonomous-execution`](../../rules/autonomous-execution.md)).
+   Same failure signature twice → the hypothesis is wrong; change approach
+   rather than spending the third attempt on a near-identical retry.
+
+   The test is **where the deliverable lives**, and it is decidable: a red check,
+   a `CONFLICTING` merge state and a stale PR head are all facts about the
+   remote. An unpushed local fix leaves every one of them exactly as it was, so
+   treating the push as optional turns the instruction into a no-op and hands the
+   user back the state they asked to have changed. This is the same reading
+   [`no-cheap-questions`](../../rules/no-cheap-questions.md) IL 5 gives prerequisite
+   work and IL 6 gives an already-named destination.
+
+   **What is still NOT covered**, so the floor keeps its teeth: an instruction
+   about the *code* only ("fix the type error", "use file X for the tests") — that
+   authorizes the edit, never the push. A red after `/create-pr` when that
+   invocation is the only authorization: its push was spent on the initial PR
+   (`commit-policy`), so the fix stays in the working tree and the re-push waits
+   for the user's fix-the-CI instruction. A push to a branch or base the user did
+   not name. A push after the named deliverable is already green. And a
+   force-push over a commit you did not author, which
+   [`git-history-discipline`](../../rules/git-history-discipline.md) gates
+   separately and which this clause never reaches.
+
+   Loop back to the top of § 4d — settle again, on the new head. Two traps make
+   this more than a restatement:
+
+   - **Stale green.** `gh pr checks` reports the last run it has, which may have
+     run against the pre-fix commit. Compare the SHA the checks ran against with
+     the PR head before reading a green as yours.
+   - **The re-push may not have landed.** A pre-push hook can refuse, and the
+     branch can be behind its OWN remote counterpart because someone pressed
+     *Update branch*. `git push` exiting non-zero means the PR still carries the
+     failure — never report the fix as delivered off a local verification.
+
+   `./scripts-run src/scripts/check_pr_ci_current` answers both in one call.
+
+**When the verdict cannot be reached** — network down, `gh` failing, the run
+never registering — say so plainly and name what is unverified. A background
+waiter that exits because `gh` errored has NOT observed a green run; treat its
+output as absent, not as a pass.
+
+**Not gated by this:** posting the status anywhere. Progress narration belongs
+in the chat reply, never as a PR comment
+([`no-pr-progress-comments`](../../rules/no-pr-progress-comments.md)).
+
+## 4f. Settings short-circuit — single read per run
+
+`commands.create_pr.preview_description`, `commands.create_pr.detail_level`
+and `commands.create_pr.screenshots` are read **once** at the top of the run and cached for the whole `/create-pr`
+invocation. Do **not** re-read `.agent-settings.yml` in Step 2 or 4b / 4e —
+every branch resolves from the cached values from step 1. The content flags
+(`detail_level`, `screenshots`) are consumed by the `/create-pr:description-only` generation step (Step 2); the
+confirmation/report flags by steps 3–4.
+
+When `preview_description` resolves to its silent default (`false`), steps
+4b + 4e collapse to the single `→ #N opened: <url>` line
+from 4b and a silent 4e. No extra file reads, no "checking settings…"
+narration, no confirmation prompts. Step 4c is never collapsed — status
+claims always carry evidence.

package/dist/agent-src/contexts/execution/pr-create-branches-freshness.md

@@ -0,0 +1,150 @@
+# PR Create — Branch Mechanics
+
+Moved body of the `/create-pr` default flow (`commands/pr/create.md`), per
+progressive disclosure. Loaded from the command's pointer lines when a run
+takes the branch a section covers — a later push, a merge, an archival sweep,
+a scope delta, a footer strip, a red CI. The Iron-Law blocks and the default
+flow skeleton stay in the command; this file carries the explanatory prose,
+rationale, and per-branch procedure.
+
+## 1b. Freshness gate — MANDATORY before opening any PR
+
+   It resolves the base itself — explicit `--base`, else the base of the **open
+   PR for this branch** as the forge reports it, else the repo default the server
+   reports for `HEAD`. Do **not** substitute
+   `git rev-list --count HEAD..origin/main`: that hardcodes a base this branch may
+   not target, and it reads the local tracking ref, which is a fetch from earlier
+   in the session — a memory, not a check (`direct-answers` Iron Law 2).
+
+   **Exit `0` is not a verdict — it means only "did not refuse".** `1` = behind.
+   `0` covers "current", "could not verify", and every path with nothing to
+   check: a no-op in CI, a detached HEAD, and standing on the base branch
+   itself. Read the line, not just the status. A run that could not reach the
+   base prints `NOT VERIFIED` and still exits `0`, deliberately, so an offline
+   push is never blocked by a network failure; treating that as a clean pass is
+   the one misread this gate cannot protect you from.
+
+   **And under `--quiet` a genuine pass prints nothing at all** — that is how
+   `taskfiles/ci-fast.yml` invokes it, so silence there is the success case, not
+   a missing verdict. Every path that has NOT verified stays loud even under
+   `--quiet`. Run it without the flag when you need to read a verdict.
+
+A branch behind its base is **not** current — bring the base in **before** the PR
+exists, never after. Auto-merge when there is no file overlap (the common case);
+only ask when an overlapping open PR makes the base genuinely ambiguous. Never
+improvise the base or silently proceed when behind **and** overlapping. The
+10-second fetch beats hours of rebase reconciliation after the parent PR lands.
+
+**After EVERY merge — not only on conflict — regenerate the derived files.**
+This is the half that gets skipped, because a merge that lands cleanly *looks*
+finished. It is not: these files are **generated**, so a clean auto-merge of
+them produces a file that describes neither side's sources. The dashboard is the
+usual casualty — it merges without a conflict marker and then reports a roadmap
+set that no longer exists.
+
+1. `./agent-config roadmap:progress` → the roadmap dashboard.
+2. `./scripts-run src/scripts/build_proof` → `docs/proof.md`.
+3. `bash src/scripts/condense.sh --sync`, then `--check` → re-projects
+   `dist/agent-src/` from the merged source.
+4. Stage the regenerated files, complete the merge, and re-run the touched
+   verification before pushing.
+
+On a **conflict**, the same four steps are the resolution — regenerate from the
+merged sources, never hand-pick hunks. Only a conflict in **hand-authored**
+content (source code, prose you or the other PR wrote) is surfaced to the user;
+a generated-file conflict never is.
+
+## 1b-ii. Update freshness — MANDATORY on EVERY later push to an open PR
+
+The gate above is not creation-only. **Every subsequent push** to a branch with
+an open PR (a CI fix, a review response, a follow-up commit) re-runs the same
+sequence first: `check_branch_freshness` → on exit `1`, bring
+`origin/{resolved-base}` in per `git.update_strategy` (merge by default; under
+`rebase` a rebase that is asked for, never a merge, and `sync_pr_branch` refuses
+a behind branch with exit 3)
+→ regenerate the derived files → verify → push (after a rebase:
+`git push --force-with-lease=refs/heads/<b>:<sha> <remote> HEAD:refs/heads/<b>`,
+never a plain push). A rebase runs only through § The rebase sequence in
+[`branch-update`](../../skills/git-workflow/references/branch-update.md):
+the ref the branch publishes is resolved from `@{push}` or the pull request's
+head repository — never `@{u}`, and an unresolved target means no rewrite — its
+SHA is pinned once after the fetch, must already be in `HEAD`, and is the lease
+unchanged — so a collaborator's push lands either before the pin and halts the
+stop, or after it and fails the lease, and is never overwritten.
+Its steps 1–3 rebase and report, then stop: the regenerate → verify above runs
+on the rebased tree, and only then does its step 4 publish, re-running step 1
+with the `SAVE` and `EXPECTED` step 3 printed.
+A PR that sits open while its base advances goes stale silently; keeping the
+base merged **at every touch** means it stays `mergeStateStatus: CLEAN` instead
+of accumulating conflicts for the moment the user wants to merge. If the gate
+exits `0`, the step costs one `ls-remote` and nothing else.
+
+Once the PR exists, this is also when the resolution gets *more* precise rather
+than less: the gate can now read the PR's real `baseRefName` from the forge, so
+a stacked or release-line PR is measured against the branch it will actually
+merge into instead of against the repo default.
+
+**The whole SEQUENCE is executable now, not just this step.** All six steps —
+fetch, integrate the base set, regenerate, verify, re-check freshness, then hand
+the push back to you — sit behind one runner, and a dry mode prints each step
+with its outcome without touching the tree. In this package that runner is the
+`push-ready` target in `taskfiles/dev.yml`; a consumer project wires the same
+six steps behind whatever its own task runner is, with steps 3 and 4 being its
+own generator and verify commands. The pre-push hook refuses and points at the
+runner; the hook never merges, because a merge inside `pre-push` rewrites the
+tree at the moment you believe your work is finished.
+
+**The resolution is executable now, not just described.**
+`agent-config git:convention sync --base origin/<base>`, `<base>` being the
+`baseRefName` of the branch's `OPEN` pull request (`gh pr view --json
+state,baseRefName`; a closed or merged one does not count, and without an open
+one the base is the default branch), fetches and merges that
+base in when the branch is behind, so a stacked or release-line PR is measured
+against what it actually merges into. It never asks the forge itself: without
+`--base` the target is the default branch, which is right only for a PR into it. The base is a
+**set**: when the PR targets something other than the default branch, whether
+the default branch joins the set is a per-target policy read from the *target's
+own commit*, never from this branch — see `src/scripts/_lib/branch_convergence.ts`.
+A non-default target with no policy entry is refused, not guessed. The default
+is merged first, so a conflict surfaces against the broader base first. On a conflict it
+STOPS and splits the conflicted paths into generated, remeasured and authored —
+the first has one correct resolution (regenerate), the second's is to re-run the
+measurement on the merged tree (a ratchet baseline, where picking a side is how
+the ratchet silently loosens), and the third has none a script may choose.
+
+**On `CONFLICTING`, run this before touching the GitHub web editor.** The web
+editor cannot tell generated from authored, so it presents a mechanical
+regenerate and a real human decision as the same three-way merge — which is the
+failure path road-to-merge-hotspot-drawdown was opened over — a branch resolved
+in the web editor while behind its base. The observation itself lives in the
+maintainer handover that roadmap cites as its Source, not in the roadmap's own
+§ 0, so do not expect to find it there. Adoption of this line is not measurable
+without telemetry this repository has ruled out; it is a checklist item, not a
+gate.
+Deliberately not in the pre-push hook: it mutates the tree, and a hook that
+rewrites the tree mid-push turns one rejected push into an unreviewed commit.
+Detection belongs in the hook and is already there; resolution is a step you run
+with the result in front of you.
+
+After it merges, REGENERATE — a clean auto-merge of a generated file is still
+wrong, and this is the step that produced the one stale-dashboard conflict on
+every merge of this branch.
+
+Where the project wires this gate into its pre-push chain, a push that goes out
+through the hook is covered without a separate step. Run it by hand when you push
+with the hook bypassed, or when you are about to open the PR some time after the
+last push — that gap is exactly where a base moves unseen.
+
+## 1c. PR-gate — archive completed roadmaps (MANDATORY)
+
+It `git mv`s each completed roadmap (that this branch touched, per
+`git log origin/main..HEAD`) into `agents/roadmaps/archive/`, rewrites inbound
+`agents/roadmaps/<x>.md` references to the archive path, regenerates the
+dashboard, and stages all of it. No agent-set annotation is involved —
+completion is read from the checkbox counts.
+
+- **It staged changes → commit them onto this branch** (`chore(roadmaps):
+  archive completed roadmaps`) and include them in the push, so the PR carries
+  the archival. Do **not** create the PR with completed-but-unarchived roadmaps
+  in the working tree.
+- **It reported nothing → proceed.** No completed roadmap in this branch.