Browser-gate enforcement: the PR hook and the skill changes — Design
Status: approved (Draft 7). Draft 7 adds F41’s rule for dependency-only changes (C-10); see ## Revisions. Since 2026-11-02 the PR hook this design describes is unregistered and its bash wrapper deleted, and the
Fast lanecheck runs only on a PR intorelease/*: a PR intomainruns no browser gate (PRD Rev 81; F40 spec Rev 9;.forge/design/harness/test-run-cost.mdS-4). The design stays as the record of how the hook worked and of the parserguard-browser-gate.mjsstill holds. Author: Dinil (Drafts 1–6); Tharinda (Draft 7) Reviewed by: three fresh-context review passes, 2026-09-28 (see ## Revisions); pass 3’s verdict was “Ready after Importants”, which Draft 4 applies. Draft 7 was checked against F41’s spec in F41’s spec review, cycles 2 and 3, 2026-09-30. Approval: Tharinda Rajapaksha (lead), 2026-09-30, in F41’s spec PR Date: 2026-09-28 · Draft 7: 2026-09-30 · approved 2026-09-30 Scope: the delivery harness — a new PreToolUse hook (.claude/hooks/), its parsing helper, its registration in.claude/settings.json, its tests and itsREADME.mdrow (F40-WI-1.3), and the browser-gate text in/forge-pre-pr-review,/forge-pr-openand/forge-deliver(F40-WI-1.4). It sets requirements on the gate program that F40-WI-1.1 builds in each app repo (§ Contract with the gate program). Spec:.forge/specs/F40-accessibility-responsive-gate-spec.mdFR-10 and FR-12. Ships inside F40’s wave 1 harness PR, not as a separate chore PR. C-10 (Draft 7) is built by F41 (.forge/specs/F41-tooling-only-dependency-bumps-spec.md) and lands in F41’s spec PR.
Context
F40 moves the browser accessibility and responsive suites into a local gate. Each app repo gets pnpm e2e:gate, which runs the whole browser suite on a clean commit and writes a result file stamped with that commit (spec FR-7). Two things enforce it:
- the last step of each app repo’s
Slow lane, which reads theBrowser gate:line in the PR description (FR-11, WI-1.1 and the developer’s CI edit); - a harness hook that refuses to open a ready PR, or mark one ready, from a Claude session unless a passing result covers the branch’s head (FR-10, WI-1.3).
The harness skills must also run and record the gate at the right moments (FR-12, WI-1.4). This record settles how the hook works and how each skill changes. The spec leaves one choice to it explicitly: how a gh command run with --repo from another checkout finds its result (FR-10 item 1).
How PRs are opened today (.claude/skills/forge-pr-open/SKILL.md, as of feature/F40-plan at e1fb7fb):
- Per-WI PRs in wave mode open as drafts, from the WI worktree, with no
--repo. Step 6 runsgit pushand thengh pr create --title … --body … --base "$PR_BASE" $DRAFT_FLAGin one block, so the draft flag and the base sit in shell variables. - Single-plan code PRs open ready, from the worktree, with no
--repo. Opening one flips the feature tophase: review. - Wave PRs open ready from the harness checkout, inside a
forloop over the wave’s repos, as a multi-linegh pr create --repo $GITHUB_ORG/$REPO_NAME --head "$WAVE_BRANCH" --base main …with backslash continuations. The app repo’s main checkout has the wave branch checked out at that point, because Stage 11 checks it out there (.claude/lib/forge-deliver/integration-scaffolds.md). - Nothing in the harness runs
gh pr readytoday (grep -rn "gh pr ready" .claude/returns nothing one1fb7fb). Stage 12 runs no/forge-pre-pr-reviewtoday. - Both app repos’
pr-validation.ymlskip theSlow laneon drafts and trigger onready_for_review, so draft → gate → ready costs oneSlow lanerun.
How harness hooks work today (.claude/hooks/README.md, .claude/hooks/block-dangerous-bash.sh): bash scripts that read the tool input with jq, match the raw command string with grep -E, exit 2 to refuse (stderr is shown to Claude) and exit 0 to allow, and fail open with a stderr warning when jq is missing. Claude Code treats any exit other than 0 and 2 as a non-blocking error, which lets the command run. The one PreToolUse hook on shell commands is registered with "matcher": "Bash" and a 5-second timeout. The app repos have no .claude/ folder, so a Claude session started inside an app repo runs no harness hook.
Terms used below. An occurrence is one place in a command where gh pr create, gh pr new or gh pr ready would run (FR-H1). An occurrence is gated when its repo is forge-et-fe or forge-et-pwa, or cannot be read, and it is not a draft or a skip.
Decisions
| # | Decision | Why |
|---|---|---|
| D-1 | One new hook, .claude/hooks/guard-browser-gate.sh, a bash wrapper like the other guards, registered as a PreToolUse hook with "matcher": "Bash|PowerShell" and "timeout": 30. |
This app runs Claude Code with both a Bash and a PowerShell tool; a gh pr create run through PowerShell would pass a Bash-only matcher. The timeout is longer than the other guards’ 5 seconds because a gated occurrence makes network calls. Commands with no PR command return within milliseconds (FR-H1). |
| D-2 | The hook does not implement the covers rule or the gate-input list itself. It calls the gate program’s own command-line entry point in the target worktree (§ Contract with the gate program). | FR-8 requires one rule for the gate, the CI step and the hook. With one implementation, AC-8b holds by construction, and the gate-input file is read by one parser. |
| D-3 | A command run with --repo from another checkout finds its worktree from the PR’s head branch: the hook looks through the worktrees of the app repo’s main checkout ($WS/<repo>, git worktree list --porcelain) for the one with the head branch checked out. If none has it, the hook refuses and says where to run the gate. This is the FR-10 item 1 choice. |
Stage 12 opens every wave PR with --repo … --head … from the harness checkout. The lookup is exact, because git lets a branch be checked out in only one worktree at a time. |
| D-4 | The head the result must cover is the pushed tip of the PR’s head branch, not the local HEAD: refs/remotes/origin/<head> after a fetch for gh pr create, the PR’s headRefOid for gh pr ready. |
The PR contains what was pushed. A result on a newer, unpushed commit is not an ancestor of the pushed tip, so the covers rule refuses it, which is correct. It follows that a push and the gh pr create after it must be separate tool calls (FR-S8), because the hook runs before any part of its tool call. |
| D-5 | The hook reads only literal values. For a gated occurrence, the repo (--repo, -R, GH_REPO), the head (--head, -H), the base (--base, -B), --body-file / -F, the draft flag and the working directory must each be readable from the command text. An unquoted token in the occurrence that is a bare expansion ($X, ${X}, $(…), a backtick substitution) could expand to any flag, so it also makes the occurrence unreadable. Unreadable → refused, with a message asking for literal values. Quoted expansions as the values of --title and --body are fine. |
Guessing could stamp the wrong PR as covered (NFR-4). The skills that open PRs are run by Claude, which writes the concrete command; FR-S8 rewrites both of /forge-pr-open’s gh pr create commands to be literal. |
| D-6 | Once an occurrence is gated, every failure is a refusal. The wrapper traps every exit on every path after the fast path and turns any non-zero status into exit 2. Network calls run with prompts disabled, under one total deadline of 20 seconds for all of the occurrence’s calls together, which also ends in a refusal. A test may shorten the deadline, never lengthen it, with GUARD_BROWSER_GATE_DEADLINE_MS. The one gap left is Claude Code itself stopping the hook at its 30-second timeout, which lets the command run. |
The spec allows failing open only when jq is missing (FR-10). The timeout gap departs from that, and is put to the lead (Q-3); the Slow lane step (FR-11) still fails such a PR. |
| D-7 | /forge-pre-pr-review --ready has a short form that runs only the gate check and the FR-4 list check. It is used where a full review of the same code has already run: on a wave branch at Stage 12, and at Stage 10 after the single-plan agent’s own full review. Elsewhere, --ready runs the full review plus the gate check. |
Every work item in a wave had its own full review and a green /forge-test-verify, and the wave PR then gets /forge-review-pr; the Stage 10 agent reviewed the same head a moment earlier. The gate result is the one thing that is new at both points. |
| D-8 | Who opens ready and who opens draft. A per-WI PR in wave mode, and the Stage 10 single-plan agent’s PR, always open as drafts (spec FR-12). A wave PR opens only when no gate input changed or a passing result covers its head. A person’s code PR opens ready in either of those two cases, and as a draft otherwise. /forge-pr-open writes the Browser gate: line into the body from the result, through covers. |
The single-plan agent cannot run the gate (it cannot keep servers running — /forge-deliver § Dispatch invariants), so the orchestrator gates its PR and marks it ready. A person who already ran the gate gets a ready PR in one step. |
| D-9 | A gate failure in /forge-deliver is routed the way Stage 7 Step 5e routes a browser-suite failure: test bug to the test specialist, in-wave code bug to the owning implementer, bounded at two repair attempts per failure class, then escalated; a real defect in an existing screen is filed as a bug and marked as a known failure (FR-21). |
Same kind of failure, same attribution rules. |
| D-10 | The hook’s tests are two scripts under .claude/hooks/tests/, run by hand and by WI-1.3’s plan; wiring them into Repo hygiene is not part of F40. |
Adding them to Repo hygiene edits .github/workflows/repo-hygiene.yml, a CI change needing lead approval and outside F40’s one approved CI change. |
| D-11 | The command is parsed by a Node helper, .claude/hooks/guard-browser-gate.mjs, not by grep patterns. The bash wrapper keeps the harness posture (jq, the fast path, exit codes); the helper tokenises the command, finds every occurrence and makes the decision. It uses only Node built-ins. |
Line-based patterns miss a --repo on a continuation line, read --draft inside a --body value as a flag, and cannot see into $(…). A tokenizer in bash is error-prone; Node is already required to run the gate and <gate-cli>. |
| D-12 | The helper finds occurrences by the word sequence, at any depth, not by where a command starts. Any unquoted gh word followed by pr, pr-level flags and create / new / ready is an occurrence, wherever it sits: at the top level, inside $(…), backticks or <(…) (also inside double quotes), inside a subshell, a group or a PowerShell $(…), (…) or {…} block, or inside the string given to a nested shell. |
Review pass 2 found that a list of command-start positions misses PR=$(gh pr create …) — the usual way to capture a PR URL — as well as if gh pr create …, PowerShell $pr = gh pr create … and try { gh pr create … }. Matching the word sequence everywhere the helper can read closes those gaps; the forms it still cannot read are listed in § Out of scope. Its cost is refusing a rare unquoted mention such as echo gh pr create, which is acceptable. It is also simpler than a list of start words. |
| D-13 | The orchestrator tells the skills which case they are in, with explicit arguments. /forge-pre-pr-review --ready --gate-only runs only the gate and FR-4 list checks (D-7’s short form); /forge-pr-open --draft always opens a draft. The orchestrator passes --gate-only at Stage 10 and Stage 12, and the Stage 10 dispatch prompt (.claude/lib/forge-deliver/agent-prompt-template.md) tells the single-plan agent to run /forge-pr-open --draft for a code PR in forge-et-fe or forge-et-pwa. |
A person’s single-plan branch and the Stage 10 agent’s branch have the same name, so a skill cannot infer the case from the branch. |
Contract with the gate program
WI-1.1 owns the gate program, its result file and the gate-input file (Decomposition Plan § Shared Contracts). The hook (WI-1.3) and the skills (WI-1.4) use them only through the entry point below. WI-1.1’s plan names the paths: <gate-cli> is scripts/browser-gate.mjs and <result-file> is .browser-gate/result.json, in both repos. /forge-deliver Stage 7 Step 2 checks that WI-1.1’s plan provides every item here.
- C-1 — No installed packages.
<gate-cli>'scovers,touches-gate-inputanddirtycommands use only Node built-ins andgit, so they run withnode <gate-cli> …in a fresh worktree beforepnpm install. This includes the lockfile parser C-10 needs: it is written for the pnpm lockfile v9 subset C-10 reads, never a YAML package fromnode_modules. - C-2 —
covers --head <sha>. Reads<result-file>in the worktree it runs in. Exit 0 only when the result ispassed, names this repo (C-8) and covers<sha>under FR-8’s rule; it then prints the result’sBrowser gate:line on stdout, byte for byte as the gate printed it, and nothing else. Exit 1 when it does not, with a one-line reason on stderr: no result file; a failed result; the result’s commit is not<sha>or an ancestor of it; or the gate-input files changed between the result’s commit and<sha>(named). A change to onlypackage.json,pnpm-lock.yamlor both that C-10 clears does not count as a gate-input change here; one that C-10 cannot clear is named with C-10’s reason. Exit 2 or more on an error, such as<sha>not present locally. A caller allows only on exit 0 and a stdout that matches FR-7’s passed-line format. - C-3 —
touches-gate-input --base <ref> --head <sha>. Compares the merge base of<ref>and<sha>with<sha>. On an answer it always exits 0, and its stdout’s first line is exactlynone(no gate input touched) or exactlytouchedfollowed by one changed gate-input path per line.nonealso covers a change to onlypackage.json,pnpm-lock.yamlor both that C-10 clears; when C-10 does not clear it, the answer istouchedwith those paths, and C-10’s reason goes to stderr, so the stdout shape does not change. Any other exit code or first line is an error. A crash in Node exits 1, so no crash can read as “none”. The CI step (FR-11) uses the same answer shape. - C-4 — The result file holds the exact line.
<result-file>stores theBrowser gate:line the gate printed as one of its fields, so the hook,/forge-pr-openandpnpm e2e:gate --pushnever format it separately. - C-5 — No fetching. No command fetches; the caller fetches first. A commit not present locally is exit 2 with “fetch first” in the message.
- C-6 —
--fe-ref <ref>on the capture app’s gate (already in WI-1.1’s success criteria): the live shared-file comparison readsforge-et-feat<ref>, defaultorigin/main./forge-deliveruses it at Stage 12 (FR-S7). - C-7 —
dirty. Always exits 0 on an answer; the first line is exactlycleanor exactlydirtyfollowed by one path per line: gate-input files with uncommitted changes, and untracked files under gate inputs./forge-pre-pr-reviewuses it (FR-S2), so no skill parses the gate-input file itself. C-10 does not apply todirty: an uncommitted change topackage.jsonorpnpm-lock.yamlis stilldirty, because the gate result must describe a real commit. - C-8 — Fixed paths, fixed fields, and a way for tests to write a result.
<gate-cli>and<result-file>are at the same repo-relative paths in both repos. WI-1.1’s plan documents the result file’s fields and howcoversidentifies the repo, so a test can write a passing or failing result without running the whole gate. - C-9 — Which version of the gate-input list applies.
scripts/browser-gate/gate-inputs.jsonandscripts/browser-gate/expected-skips.jsonare always gate inputs, whatever any version of the list says, so a change that narrows either one always needs a gate run (FR-8).coversandtouches-gate-inputread the list from commits withgit show, never from the working tree, and apply the union of the list at both commits they compare (the result’s commit and<sha>; the merge base and<sha>).dirtyapplies the union of the list atHEADand the list on disk. A branch, or an uncommitted edit, that drops an entry from the list therefore cannot make an answernoneorclean. C-10’s two package lists follow the opposite, equally conservative rule: a package counts as listed only if every version read lists it (the intersection), so a list that is wider on one side can never make an answernone. - C-10 — Dependency-only changes (F41). When the only gate inputs that changed between the two commits
coversortouches-gate-inputcompares are amongpackage.jsonandpnpm-lock.yaml(either or both), the change counts as touching no gate input only if F41 FR-2’s three conditions hold:package.jsondiffers only in dependency version specifiers; every lockfile section other thanimporters,packagesandsnapshotsis identical; and the gate graph is identical. The gate graph is walked from the root importer’s direct dependencies that are on neither ofgate-inputs.json’s two package lists (types-only packages, and tools not run by the gate), through each snapshot’sdependenciesandoptionalDependencies. A types-only package is never entered (an aliased root or edge counts as listed only when both its names are on the same list); a node is its snapshot key with types-only peer segments removed at any depth; and the nodes, theirpackagesentries and their edges must all be identical. Anything C-10 cannot analyse — an unparseable lockfile, an unsupportedlockfileVersion, a second importer, a non-registry resolution, two keys that collapse into one node, an alias whose two names differ in list membership, or an unresolved reference — counts as touching a gate input (fail closed). The rule is one pure function inscripts/browser-gate/rules.mjs, which the CI description check (FR-11) calls too, so the hook, the skills and CI give the same answer. F41’s spec (.forge/specs/F41-tooling-only-dependency-bumps-spec.mdFR-1 to FR-6) is the full statement; this record states only what the hook and the skills rely on. The hook’s code does not change, because it reads only the answers ofcoversandtouches-gate-input.
Requirements
The hook (WI-1.3)
-
FR-H1 — Finding occurrences. The wrapper reads
tool_name,tool_input.commandand the input’scwd.- Fast path: one in-shell match (
[[ $cmd =~ … ]], over the whole multi-line text, never a line-by-linegrep): if the text does not contain the wordgh(orgh.exe) followed somewhere later byprand one ofcreate,neworready, the wrapper exits 0 with no further call (NFR-H1). Otherwise it passes the input to the helper. - Tokenising, Bash: backslash-newlines are joined;
#comments at the start of a word are skipped; single quotes,$'…', double quotes and here-document bodies are units;$(…), backticks and<(…)are parsed recursively, also inside double quotes; a simple command ends at an unquoted;,&&,||,|,&or newline at its own depth, or at the end of the substitution, subshell or group it sits in.case WORD in … esac(BUG-044): an unquotedcasein command position opens a case statement; each pattern list, with an optional leading(and|between patterns, ends at its unquoted); an arm’s list ends at;;,;∨;&, or at anesacin command position. The word and the patterns are read for$(…)and backticks, each run in its own shell. The statement runs in the same shell, and acdorGH_REPOinside an arm counts for an occurrence only inside that arm (joined to it as FR-H4 says); for anything outside the arm it is uncertain, as one under&&or||is. A case the helper cannot read — noin, noesac, an empty pattern, an extglob(inside a pattern (@(a|b)), a word or(right afteresac— is refused as unparseable, and so is;;,;∨;&outside a case, which bash also rejects. A reserved word (case,in,esac,{,},if,then,timeand the others) is recognised only when it is unquoted and unescaped, after backslash-newlines are removed (ca\⏎seiscase;"then"and\caseare command names);time -pandtime --stay in command position;coprocis refused as unparseable. A(right after a word is refused, as bash refuses it, except in an array assignment (a=(…)), a function definition (f ( )), a C-stylefor ((…))and inside[[ … ]].if … fi, andwhile,until,forandselect … done(BUG-098), are each read as one statement, as a{ …; }group is, ending at thefiordonein command position that matches its opening word (or, forforandselect, at the}of a{ … }body in place ofdo … done); a redirection,|or&after it belongs to the whole statement. An unclosed statement, afiordonewith nothing of its kind open, and a word right afterfiordoneare refused as unparseable, as bash rejects them. A group or statement after a reserved-word prefix (! { …; },time if …) shares the prefix’s pipeline element, so a|or&&before the prefix applies to it. - Tokenising, PowerShell:
#line comments and<# … #>block comments are skipped; single and double quotes, the backtick escape and here-strings are units;$(…),(…)and{…}are parsed recursively, also inside double quotes; a simple command ends at an unquoted;,|,&&,||or newline at its own depth. - Unquoted here-documents: a here-document whose delimiter is not quoted (
<<EOF, not<<'EOF') has its$(…)and backtick expansions parsed as above, because bash runs them. - Nested shells, tokenised the same way, one level deep: the string argument of
bash,shorzshwith any flag bundle containingc(-c,-lc,-ec),eval,pwsh/powershell-c/-Command,Invoke-Expression/iex, andcmd /c; and text a shell reads on standard input — a here-document or here-string fed to one of those shells (bash <<'EOF'), or a pipe into one (… | bash,… | iex). - PowerShell
--%: the text after the stop-parsing token is read as plain words, by native-argument rules. - An occurrence is, at any depth (D-12): an unquoted
ghword —gh,gh.exe, or a path ending in/ghor/gh.exe(either slash), also when the path is quoted as a command (& 'C:\Program Files\GitHub CLI\gh.exe') or given toStart-Process— thenpr; then anypr-level-R/--repoflag with its value; thencreate,new(an alias ofcreate) orready. It runs to the end of its simple command, and only its own tokens are read, usinggh’s flag list: a flag that takes a value consumes the next word, so--title --draftis a title, not a draft. - A command that does not tokenise (an unbalanced quote or bracket) and passed the fast path is refused. Each occurrence is judged on its own; the command is refused if any occurrence is refused.
- The
ghword is matched ignoring letter case (GH.exe), because Windows file names are not case-sensitive. - Text a shell reads from a source the helper cannot see (
cat script.sh | bash,bash < file) is not checked (§ Out of scope). When such a form sits in a command that passed the fast path, the command is refused, because the helper cannot tell whether theghtext it matched runs there. This includes a shell in command position that reads standard input with no here-document, here-string or pipe of its own: it reads what it inherits, which can come from a pipe or redirection on an enclosing case, group, subshell orif/while/forbody (echo … | case x in *) bash;; esac), so it is refused wherever it stands (BUG-044 review). - Order of the checks, per occurrence: FR-H1a (readability), then FR-H2 (drafts and other allowed forms), then FR-H3 (skip line and repo), then FR-H5 and FR-H6.
- Fast path: one in-shell match (
-
FR-H1a — Unreadable occurrences are refused first. Before any other check, an occurrence is unreadable, and refused with the literal-values message (D-5), when any of its own tokens is a bare expansion (
$X,${X},$(…), a backtick substitution — each could expand to more flags, including a second--repo, whichghtakes as the last one given, or a--draft=false), or a quoted non-literal word ("$X") that is not the value of a value flag (it is one argumentghwould read as a flag, such as--repo=…or--draft=false), or a flaggh pr create/gh pr readydoes not define. Sogh pr create --repo altrium-io/forge-et-harness $FLAGSis refused, not allowed as a harness PR. -
FR-H2 — Allowed at once. An occurrence whose draft flag, read as
ghreads it (the last--draft/-dtoken decides), is a bare--draft, a bare-dor--draft=true; an occurrence with--dry-runor--help/-h; andgh pr ready --undo, are allowed. Any other--draft=…value is not a draft; any other token starting-dmakes the occurrence unreadable. -
FR-H3 — Which repo, and the skip line.
- Repo, from local sources, in this order: the occurrence’s
-R/--repovalue (also--repo=v,-R=vand the joined-Rv); forgh pr ready, the repo in a URL argument; aGH_REPO=…word anywhere earlier in the same simple command (a prefix assignment, or afterenv,command,nohuportime), or earlier at the same or an outer depth of the command (export GH_REPO=…,GH_REPO=…;, PowerShell$env:GH_REPO = '…'), or in the hook’s own environment; otherwise theoriginremote of FR-H4’s directory. If the textGH_REPOappears in the command in any form the helper does not read, the repo is unreadable. Accepted forms:OWNER/REPO,HOST/OWNER/REPO, HTTPS and SSH URLs with or without.git. Repo names are compared ignoring case. A directory with more than one remote needs--repo. gh pr create: if the occurrence’s own--body/-bvalue (also--body=v,-bv), or the file named by its--body-file/-F(also-F=v,-Fv; resolved against FR-H4’s directory;-for standard input cannot be read), carries a line matching exactly^Browser gate: skipped — [^[:space:]].*$(the em dash; a non-empty reason), the occurrence is allowed, whatever its repo. Otherwise, a repo that is read and is notforge-et-feorforge-et-pwais allowed; a repo that cannot be read is refused (D-5).gh pr ready: a repo read from local sources that is notforge-et-feorforge-et-pwais allowed, with no network call. Otherwisegh pr view(FR-H5) supplies the repo from the PR’s URL and the body; a non-gated repo is allowed, and a body with the skip line is allowed.
- Repo, from local sources, in this order: the occurrence’s
-
FR-H4 — Which directory. The last literal
cd,pushd,chdir,Set-Location,slorPush-Location(with or without-Path/-LiteralPath) that runs before the occurrence at the occurrence’s own depth or an outer one, resolved against the input’scwd; otherwise the input’scwd. A directory change inside a subshell (( … )), a command substitution, a process substitution or a nested shell that does not contain the occurrence has no effect on it. A directory change inside a construct that runs in the same shell — a bash{ …; }group,if/while/until/for/selectbodies, or a PowerShell{ … }/try { … } catch { … }block — does take effect, so it counts when it runs before the occurrence, unless the bash construct is itself a pipeline element or a background job (if …; then cd x; fi | cat), which bash runs in a subshell.popd,cd -,cdwith no argument,Pop-Location, and a target containing a variable or substitution make the directory unreadable. Windows paths are normalised (\to/), and the wrapper exportsMSYS_NO_PATHCONV=1so Git Bash does not rewriteref:patharguments. -
FR-H5 — Head, base and worktree.
gh pr create: the head branch is--head/-H/--head=/-Hv(anowner:branchvalue keepsbranch), or the current branch of FR-H4’s directory; the base is--base/-B/--base=/-Bv, ormain.gh pr ready [<number> | <url> | <branch>]:gh pr view <arg> [--repo …] --json url,headRefName,headRefOid,baseRefName,bodygives all of them. If it fails, the occurrence is refused with its error.- The worktree is FR-H4’s directory when its
originis the target repo and its current branch is the head branch; otherwise the one non-prunableworktree of$WS/<repo>that has the head branch checked out (D-3; a detached checkout is not found).$WSis the parent of the harness’s main checkout: the parent of the parent ofgit -C "$CLAUDE_PROJECT_DIR" rev-parse --path-format=absolute --git-common-dir(git 2.31 or later). No such worktree → refused, naming the branch and the command to run.
-
FR-H6 — The decision. In the worktree, with
GIT_TERMINAL_PROMPT=0,GCM_INTERACTIVE=never,GH_PROMPT_DISABLED=1and git’s low-speed limits set, under D-6’s total deadline:git fetch -q origin <head> <base>(it updates only remote-tracking refs). A head branch not onorigin→ refused with “push it first, as its own tool call”. The head commit isrefs/remotes/origin/<head>forcreate,headRefOidforready.node <gate-cli> touches-gate-input --base origin/<base> --head <head-sha>: exit 0 with first linenone→ allowed (FR-10 item 2); exit 0 withtouched→ step 3; anything else → refused with the error.node <gate-cli> covers --head <head-sha>: exit 0 with a well-formed passed line → allowed (FR-10 item 1); exit 1 → refused, passing the program’s reason on; anything else → refused with the error.<gate-cli>missing (the branch predates F40): if the base ismain, refused with “mergemainin”; otherwise (a hotfix on arelease/*cut before F40, where mergingmainis forbidden) refused with “putBrowser gate: skipped — <reason>in the body”.
-
FR-H7 — The refusal message. One short block on stderr, exit 2. It names the repo, the branch and the head commit, the reason, and the command that fixes it. When the worktree’s local
HEADis ahead of the pushed tip, the fix it names is “push throughpnpm e2e:gate --push”. For example:Blocked by Forge harness: forge-et-fe PR from feature/F5-c-wave-1 has no passing browser gate for 3f2a9c1. Reason: the last result (a81e0d4) is older, and src/ changed since. Run, in C:/Users/…/forge-et/forge-et-fe: pnpm e2e:gate --push Then run the gh command again. To skip, put "Browser gate: skipped — <reason>" in the PR body (--body-file). -
FR-H8 — Dependencies. Without
jq, the wrapper printsguard-browser-gate: jq not found — browser gate guard skippedon stderr and exits 0, as the other guards do.gitandghare required by the commands it guards. Withoutnode, every command that passes the fast path is refused with “node not on the Git Bash PATH”, because the wrapper cannot tell a draft or a harness PR from a gated one without the helper (Q-2). -
FR-H9 — Registration and docs.
.claude/settings.jsongains the D-1 entry afterblock-dangerous-bash.sh..claude/hooks/README.mdgains a table row (what it blocks; its dependencies; the accepted gaps in § Out of scope and D-6) and a line under § Dependencies.
The skills (WI-1.4)
-
FR-S1 —
/forge-pre-pr-reviewtakes--ready [--gate-only] [--base <ref>]. § Invocation modes changes from “takes no arguments” to an optional--ready, meaning “this diff is about to be opened ready for review, or marked ready”; an optional--gate-only, meaning “run only the gate and FR-4 list checks” (D-7, D-13); and an optional--base <ref>for the PR’s base (defaultorigin/main; a hotfix passes itsorigin/release/v…branch).--gate-onlyis valid only with--ready; on its own the skill stops with a usage line. The orchestrator passes--ready --gate-onlyat Stage 10 and Stage 12 (FR-S5, FR-S6), running the skill with that checkout as its working directory; a person passes--readybefore opening a ready fix, hotfix or chore PR in either app repo. -
FR-S2 — The browser-gate check. A new Step 3 category, Browser gate (
forge-et-fe/forge-et-pwadiffs). The skill first runsgit fetch -q origin(C-5). The check applies whentouches-gate-input --base <base> --head HEADanswerstouched, ordirtyanswersdirty. On a branch that has noscripts/browser-gate.mjs(it predates F40), the skill cannot ask the program, so the check applies when the diff against<base>changes any file that is not markdown (*.md):- with
--ready:covers --head HEADnot exit 0 (no result, a failed result, a result that does not coverHEAD) → Blocker, citing the program’s reason andpnpm e2e:gate;dirty→ Blocker (“commit, then run the gate”); a branch without<gate-cli>→ Blocker (“mergemainin”, or the skip line on a pre-F40release/*base); - without
--ready(a per-WI draft branch, uncommitted work, the Stage 10 agent’s own run): the same findings as one advisory line in the verdict’s preamble, not a Blocker, stating that the gate must pass before the PR is ready.
- with
-
FR-S3 — The FR-4 list check. In the Accessibility category: a frontend diff that adds a new query-string value or data state to an existing route — for example a new
?login=value, or a new empty, error or reconnect state of a routed page — and does not add its entry toe2e/pageStates.ts(the FR-4 list, named by WI-1.5’s plan) → Important, naming the state. With and without--ready. -
FR-S4 — The short form,
--ready --gate-only(D-7, D-13). Step 0’s audit precondition is replaced by a preamble that reads the relevant audit files and quotes their latest verdicts (the wave’s per-WI audits at Stage 12, the single-plan audit at Stage 10); the skill then runs FR-S2 and FR-S3 only, and says so. When a person runs--readyon a branch Step 0 cannot map to an audit file (hotfix/*,chore/*, afix/BUG-*with no audit), the skill says the full review needs a plan and an audit and suggests--ready --gate-only.--readydiffs against<base>, not the localmain, which in a main checkout can be far behindorigin/main. The Stage 12 verdict is recorded in the Decomposition Plan’s## Notes, and/forge-pr-open --wavesummarises it in the wave PR body (FR-S8). -
FR-S5 —
/forge-deliverStage 10 (single-plan) for a code PR inforge-et-feorforge-et-pwa. The agent opens the PR with/forge-pr-open --draft(D-8, D-13), and/forge-pr-openleaves the feature atphase: devwhile any of its code PRs is a draft (FR-S8). After the agent returns with the PR URL, the orchestrator, in the agent’s worktree:- runs
git fetch -q originandtouches-gate-input --base origin/<base> --head HEAD; onnoneit skips to step 5 with no gate run; - runs
pnpm install --frozen-lockfile; stops any dev server it has running; makes sure the backend is up (forge-et-fe); forforge-et-pwa, runsgit -C "$WS/forge-et-fe" fetch -q origin, so the live shared-file comparison reads a currentorigin/main; - runs
pnpm e2e:gate --push; on failure, routes it as D-9, then re-runs; - runs
/forge-pre-pr-review --ready --gate-only(FR-S4) with the worktree as its working directory; a Blocker is routed to the implementer, and the orchestrator re-runs from step 3 if a gate input changed; - runs
cd <worktree> && gh pr ready <number>, so the hook reads that worktree’s result; then, once every touched repo’s code PR is open and ready, flips the featuredev → review(the flip/forge-pr-openmakes today for a ready PR).
Resume: Stage 10’s entry check treats an open code PR as done only when it is ready; an open draft PR in
forge-et-feorforge-et-pwaresumes at step 1. The Resume Protocol’s row “phase: dev, single-plan — code PR open → Stage 15” and the Stage map box (kept equal by the INVARIANT comment) change to “code PR open and ready in every touched repo”. Aforge-et-be-only single-plan PR is unchanged. - runs
-
FR-S6 —
/forge-deliverStage 12, a new first step “Browser gate”. For each touched repo that isforge-et-feorforge-et-pwa, beforeforge-pr-open --wave <N>, with the repo’s main checkout (which Stage 11 left on the wave branch) as the working directory:- confirm
HEADequalsorigin/feature/<ticket>-wave-<N>; runtouches-gate-input --base origin/main --head HEAD; onnone, skip the rest of this step for the repo; - run
pnpm install --frozen-lockfile; stop any dev server from Steps 5d–5g; make sure the backend is up (forge-et-fe); forforge-et-pwa, rungit -C "$WS/forge-et-fe" fetch -q origin; - run
pnpm e2e:gate(with--fe-ref, FR-S7); on failure, route it as D-9, re-integrate the fix (a Pass-1-style merge, then push), and re-run; - run
/forge-pre-pr-review --ready --gate-only(FR-S4).
Then
forge-pr-open --wave <N>writes the line into each body (FR-S8), so the PR’s first CI run already passes theSlow lanestep. - confirm
-
FR-S7 — Both app repos in one wave. When a wave touches both
forge-et-feandforge-et-pwa, the capture app’s gate in FR-S6 always runs with--fe-ref origin/feature/<ticket>-wave-<N>(C-6). The Stage 13 halt block then states the merge order: merge theforge-et-fewave PR first;git -C "$WS/forge-et-fe" fetch origin; re-runpnpm e2e:gate --pushinforge-et-pwaon its wave branch (now againstorigin/main); then merge theforge-et-pwawave PR. The re-run is a procedure only: neither the covers rule nor CI can see whichforge-et-feref a result was made against. -
FR-S8 —
/forge-pr-open, code mode,forge-et-feandforge-et-pwaonly.- Literal commands (D-5). Step 6’s
gh pr createcarries a literal--base <branch>, and a literal--draftwhen the PR opens as a draft, instead of"$PR_BASE"and$DRAFT_FLAG. The wave-mode command is written as one literalgh pr create --repo <org>/<repo> --head feature/<ticket>-wave-<N> --base main …per repo, not aforloop over variables. Everygh pr createandgh pr readythe skill runs starts withcd <checkout> &&(AC-H7’s fallback). - The push is its own tool call (D-4): step 6’s
git pushruns, and finishes, before thegh pr createtool call. - Ready or draft (D-8). Step 4 runs
touches-gate-inputand then, ontouched,covers --head <head-sha>, in the checkout that holds the branch (the worktree for per-WI and single-plan PRs; the main checkout for a wave PR). A per-WI PR in wave mode, and any PR opened with--draft(the Stage 10 agent passes it, D-13), always open as drafts. A wave PR opens only onnoneor acoversexit 0; otherwise the skill stops with the program’s reason and “runpnpm e2e:gatefirst”. A person’s code PR opens ready onnoneor acoversexit 0, and as a draft otherwise, and then prints the next steps:pnpm e2e:gate --push, thencd <worktree> && gh pr ready <number>. - Phase. In single-plan mode,
/forge-pr-openflips the featuredev → reviewonly when every touched repo’s code PR is open and ready. A draft PR in these repos, including one alongside a readyforge-et-bePR, leaves the feature atphase: dev;/forge-deliverflips it aftergh pr ready(FR-S5). - The body. On a
coversexit 0, the printed line goes alone on its own line under## Verification, with a pre-ticked item “Browser gate passed — see theBrowser gate:line” (the item does not repeat the counts, which a later--pushrewrites). A wave PR’s body also summarises the Stage 12 short-form verdict from the Decomposition Plan’s## Notes; no line of that summary may start withBrowser gate:at column 0, because theSlow lanecheck accepts exactly one such line. A PR with no gate-input change carries no line. A draft without a covering result opens without the line (theSlow laneskips drafts).
- Literal commands (D-5). Step 6’s
-
FR-S9 — Later pushes to an open app-repo wave PR. The Stage 13 halt block, and Stage 14’s “PR still open” message, say that any push to an open
forge-et-feorforge-et-pwawave PR that changes a gate input — a fix from/forge-review-pr’s findings, or a merge ofmaininto the wave branch — is made withpnpm e2e:gate --pushfrom the checkout holding the wave branch, never as a plaingit pushfollowed by a gate run (FR-7’s one-CI-run ordering). -
FR-S10 — Dispatch invariant 3 names the gate.
/forge-deliver§ Dispatch invariants, item 3, addspnpm e2e:gateto the live runs only the main session makes. No dispatched agent runs the gate.
Non-functional requirements
- NFR-H1 — Fast when it does not apply. A Bash or PowerShell command that fails the fast path costs one
jqread and one in-shell match; nogit,ghornodecall. - NFR-H2 — No false passes (spec NFR-4). A gated occurrence is allowed only through FR-H2, FR-H3’s exact skip line or repo test, or FR-H6’s two program answers. Every other path, including an error, refuses. D-6’s timeout is the one accepted exception.
- NFR-H3 — Works on Windows and macOS. Git Bash on Windows, as for every harness hook; no GNU-only flags (
grep -P,sed -i,readlink -f); the wrapper is shellcheck clean at error severity, whichRepo hygienechecks; the helper passesnode --check.
Acceptance criteria
These refine the spec’s AC-8b, AC-10 and AC-12a; the spec’s criteria stay the ones signed off.
- AC-H1 (FR-H1, FR-H2, D-12) — the helper’s unit tests (
node --test) cover as occurrences: the wave-modegh pr createwith--repoon a backslash-continued line;PR=$(gh pr create --repo altrium-io/forge-et-fe …);`gh pr create …`;if gh pr create …; then;( gh pr create … ); PowerShell$pr = gh pr create …,try { gh pr create … }and& gh pr create …;gh.exe,/usr/bin/gh;gh pr -R o/r create;bash -c "gh pr create …". Not occurrences:git commit -m "… gh pr create …"and a quotedecho "gh pr create". Allowed: a bare--draft,-d,--draft=true,--dry-run,gh pr ready --undo. Not drafts:--draft=false,--draft=f, and--body "use --draft next time". Refused: an unbalanced quote. A harnessgh pr createpreceded by# Stage 12's PR, and one with a--body "$(cat <<'EOF' … it's (x … EOF)"body, are allowed. The wrapper’s fixture script shows that a command failing the fast path runs nonode. - AC-H2 (FR-H3, FR-H4, D-5) — a PR command for
forge-et-harnessorforge-et-beis allowed;cd <fe-worktree> && gh pr create …resolvesforge-et-fe;gh pr create --repo "$ORG/$REPO",--base "$B"and a bare$DRAFT_FLAGtoken are refused with the literal-values message;-Raltrium-io/forge-et-feand--repo altrium-io/Forge-ET-FEresolveforge-et-fe;export GH_REPO=altrium-io/forge-et-fe; gh pr createresolvesforge-et-fe;Set-Location -Path <dir>; gh pr create …resolves the directory;cd <fe-wt>; (cd <harness>); gh pr createresolves the fe worktree;cd -; gh pr createis unreadable;gh pr ready https://github.com/altrium-io/forge-et-fe/pull/1from the harness resolvesforge-et-fe;gh pr ready 12 --repo altrium-io/forge-et-harnessis allowed with nogh pr viewcall./forge-pr-open’s rewritten literal wave-mode command resolves its repo, head and base. - AC-H3 (FR-H3) —
Browser gate: skipped — no UI changein the occurrence’s--bodyor--body-fileis allowed, even with an unreadable repo; the same text in an unrelatedecho, or in a second PR command’s body, is not;Browser gate: skipped —with no reason, andBrowser gate: skipped - xwith a hyphen, are not. - AC-H4 (FR-H5, FR-H6, D-3, D-4) — the wrapper’s fixture script, with temporary repos whose
originis a local bare repository namedforge-et-fe, a stub<gate-cli>and a stubghonPATH: no result → refused with the program’s reason andpnpm e2e:gate --push; covering result → allowed;touches-gate-inputansweringnone→ allowed; a stub that crashes (exit 1, no output) → refused; branch not onorigin→ refused with “push it first”;--repo … --head <branch>from the harness finds the worktree holding the branch, and a harness branch of the same name is not mistaken for it; no worktree holds it → refused naming the branch;gh pr readyreads head, base and body from the stubbedgh pr view; a hang past a shortened deadline → refused. - AC-H5 (FR-H6, FR-H8) — missing
<gate-cli>with basemain→ “mergemainin”, with arelease/*base → the skip-line message;nodemissing → refused;jqmissing → warning on stderr and allowed. - AC-H6 (AC-8b) — the fixture script takes
--fe-checkout <path>and, against aforge-et-fecheckout carrying the real<gate-cli>, runs the spec’s AC-8 A/B cases through the hook. WI-1.3’s/forge-test-verifycovers AC-H1 to AC-H5 only. The orchestrator runs AC-H6 after Pass 1 of F40’s wave 1 and before Stage 12, with the hook from the harness checkout offeature/F40-wave-1(which holds WI-1.3’s code after Pass 1), against$WS/forge-et-feonfeature/F40-wave-1, and records the result in WI-1.3’s## Progresson the plan branch; a failure is routed to WI-1.1 (the rule’s code) or WI-1.3 (the hook), as D-9. WI-2.2 re-runs it. - AC-H7 (FR-H4, live) — WI-2.2 checks, from a real Claude session, whether the hook input’s
cwdfollows acdorSet-Locationmade in an earlier tool call: with the shell already in aforge-et-feworktree from a previous call, a baregh pr create(Bash and PowerShell) must be refused. Ifcwddoes not follow, the fallback already holds: everygh prcommand the skills and the orchestrator run starts withcd <checkout> &&(FR-S8), and theSlow lanestep fails any PR opened otherwise. The finding goes to the lead either way. - AC-S1 (FR-S1 to FR-S10) — the spec’s AC-12a greps find the text, and each FR-S item has a sentence in the named skill that says what it says here. The skills in use are WI-2.2 (AC-12d).
Scope
In scope
- The hook, its helper, its registration, its tests and its README row (WI-1.3).
- The text changes in
/forge-pre-pr-review,/forge-pr-openand/forge-deliverdescribed in FR-S1 to FR-S10, and the Stage 10 dispatch prompt’s/forge-pr-open --draftline in.claude/lib/forge-deliver/agent-prompt-template.md(D-13) (WI-1.4). - The contract items C-1 to C-9, which WI-1.1 builds, and C-10, which F41 builds.
Out of scope
- Gating a PR created any other way: from the GitHub website, with
gh api, from a terminal outside Claude Code, or from a Claude session started inside an app repo (no.claude/there). TheSlow lanestep (FR-11) catches these (spec W-7). - Commands the helper cannot see into: a script file, a user-defined
ghalias, a nested shell more than one level deep, a command built at run time from variables ($cmd pr create), and a keyword split by quotes or escapes so the fast path does not see it as contiguous text (g''h,cr\eate,$'gh\x20pr', PowerShell backtick escapes). No skill writes these forms. Listed in the README row. - A PR that changes the gate program is judged by the changed program. The hook runs the branch’s own
<gate-cli>, and CI’s check runs the PR’s own copy, so a change underscripts/that weakens the rule would pass its own check. Review of changes underscripts/is the control; this is an accepted limit. - Checking that the PR body carries the
Browser gate: passedline. TheSlow lanestep checks it, and/forge-pr-openandpnpm e2e:gate --pushwrite it. - Gating
forge-et-bePRs (spec Out of Scope). - Extending
block-dangerous-bash.shto PowerShell commands; that guard’s gap is a separate harness change. - Wiring the tests into
Repo hygiene(D-10).
Where each rule lives
| Rule | File |
|---|---|
| The fast path, the posture, the exit codes | .claude/hooks/guard-browser-gate.sh (header comment) |
| The tokenizer and the decision | .claude/hooks/guard-browser-gate.mjs |
| The hook’s limits | .claude/hooks/README.md |
| The registration | .claude/settings.json |
--ready, the short form, the gate check, the FR-4 list check |
.claude/skills/forge-pre-pr-review/SKILL.md |
| Literal commands, the separate push, ready-or-draft, the phase, the line in the body | .claude/skills/forge-pr-open/SKILL.md |
| Stage 10’s gate-then-ready sequence and resume (including the Resume Protocol row and the Stage map box), Stage 12’s gate step, the later-push rule, the merge order, invariant 3 | .claude/commands/forge-deliver.md |
The Stage 10 agent’s /forge-pr-open --draft |
.claude/lib/forge-deliver/agent-prompt-template.md |
| The covers rule, the gate-input list, the result file | each app repo’s gate program (WI-1.1) |
| The two package lists and the dependency-only rule (C-10) | each app repo’s scripts/browser-gate/gate-inputs.json and rules.mjs (F41) |
| Why | this record |
Open questions
- Q-1 — D-7’s short form at Stage 12 and Stage 10. Proposed: keep (review passes 1 and 2 agreed; pass 2 asked for Stage 10 to use it too, which D-7 now does).
- Q-2 — FR-H8 refuses every command that passes the fast path when
nodeis missing, following the spec’s “fails open only whenjqis missing”. A developer withoutnodecannot run the gate in any case. Proposed: keep (both passes agreed). - Q-3 — for the lead. D-6 leaves one path where a gated command runs unchecked: Claude Code stopping the hook at its 30-second timeout. This departs from the spec’s “fails open only when
jqis missing” (FR-10). The wrapper’s trap covers every exit after the fast path, and the 20-second total deadline makes the timeout unlikely; theSlow lanestep still fails the PR. Proposed: accept, recorded here.
Revisions
Draft 2 — 2026-09-28 (before approval)
Fresh-context review pass 1 returned “Needs another pass” with four Blockers; the WI-1.3 plan author raised overlapping questions. Changes:
touches-gate-inputcould read a crash as “none” (a false pass): C-3 now answers with exit 0 plus an exactnone/touchedfirst line;coversneeds exit 0 plus a well-formed line (C-2).- A
--repoon a continuation line was missed (a false pass on Stage 12’s own path), and flags were read from anywhere in the text: parsing moves to a Node tokenizer (D-11), and flags and the skip line come only from the occurrence’s own tokens. /forge-pr-open’s$DRAFT_FLAGand"$PR_BASE"would have made every per-WI draft PR unreadable: FR-S8 rewrites step 6 with literal values, and D-5 names the base, the body file and bare expansions.gh pr ready <url>from the harness resolved to the harness: the repo comes from the URL.- Also: failures after gating refuse (D-6; Q-3 for the lead); prompts disabled and an internal deadline; more
GH_REPOand PowerShell forms; the working directory must be a checkout of the target repo; contract items C-7 (dirty) and C-8 (fixed paths, result fields for tests); a named run of AC-8b’s cases after Pass 1 (AC-H6) and a livecwdcheck (AC-H7);pnpm install --frozen-lockfilebefore each orchestrator gate run; a pre-F40release/*base points at the skip line;/forge-pr-openopens ready when a result already covers the head (D-8);--fe-refwhenever both app repos are in a wave.
Draft 3 — 2026-09-28 (before approval)
Fresh-context review pass 2 returned “Needs another pass” with two new Blockers; the WI-1.3 and WI-1.4 plan authors raised questions. Changes:
- A PR command inside
$(…),if, a PowerShell assignment or atryblock was never checked (a false pass): occurrences are now found by the word sequence at any depth (D-12, FR-H1), with those forms in AC-H1. - The wave-mode
gh pr createwas not literal (it runs in aforloop over variables), so the hook would have refused Stage 12’s main path: FR-S8 writes it as one literal command per repo; the Context bullet is corrected. - The fast path was described as a line-by-line
grep, which misses a continued command: it is one in-shell match over the whole text (FR-H1, NFR-H1). Withoutnode, every command past the fast path is refused (FR-H8). - Harness PRs could be refused by mistake: comments and
$'…'are handled; tests added (AC-H1). - Joined short flags and letter case could miss the repo:
-Rv/-R=vand the like are read, and repo names are compared ignoring case (FR-H3, FR-H5). - A directory change inside a subshell could mislead the directory: scope rules added (FR-H4).
- An uncommitted edit to the gate-input list could change an answer: C-9 reads the list from commits; C-2 names the “not an ancestor” reason.
- The push and
gh pr createin one tool call would be refused, because the hook runs first: they are separate calls (D-4, FR-S8). - A wave with no gate-input change had no way to open:
touches-gate-inputruns first in FR-S5, FR-S6 and FR-S8, andnoneneeds no gate run. --readycould not run on hotfix, chore or unaudited fix branches: FR-S4 gives them the short form, and FR-S1 adds--base.- Stage 10 could skip the gate on resume, because opening the draft flipped the feature to
review: a single-plan draft leaves the feature atdev,/forge-deliverflips it aftergh pr ready, and an open draft resumes Stage 10 (FR-S5, FR-S8). - AC-H6’s timing was impossible in the pipeline order: it runs after Pass 1, before Stage 12, and is recorded in WI-1.3’s Progress. AC-H7 now names its fallback (
cd <checkout> &&on every skill command). - Also: the short form applies at Stage 10 (D-7); the pre-ticked item points at the line instead of repeating its counts; the Stage 12 verdict’s home is the Decomposition Plan’s
## Notes;--readydiffs against the base, not the stale localmain;gh pr readyon a non-gated repo makes no network call; only bare--draft,-dand--draft=truecount as drafts, and--dry-runis allowed; the Stage 10 agent always opens a draft; the deadline is a total, with a test override that can only shorten it; the terms “occurrence” and “gated” are defined; FR-S2 fetches first; the gate program’s real paths are named.
Draft 4 — 2026-09-28 (before approval)
Fresh-context review pass 3 returned “Ready after Importants”: pass 2’s Blockers closed, no new Blocker, and C-1 to C-8 match WI-1.1’s plan. Changes:
- A branch could narrow the gate-input list and pass its own check: C-9 makes the list file and the expected-skip list always gate inputs, and applies the union of the list at both compared commits (
dirty: atHEADand on disk). WI-1.1’s plan must reconcile its list-at-head and list-on-disk choices. - Forms the helper could not see: stdin shells, unquoted here-document expansions, combined
-cflag bundles,iex,cmd /c,Start-Process, a quotedghpath and PowerShell’s--%are now read (FR-H1); D-12’s “cannot miss” claim is reworded; what is left is listed in § Out of scope. env GH_REPO=… gh pr createfrom the harness resolved to the harness: anyGH_REPO=word earlier in the simple command is read, and an unreadGH_REPOmakes the repo unreadable (FR-H3).- The skills could not tell the Stage 10 agent from a person: explicit
--gate-onlyand--draftarguments (D-13; FR-S1, FR-S4, FR-S5, FR-S8), and the Stage 10 dispatch prompt joins the scope. - A mixed-repo single-plan feature could skip the gate on resume: the feature flips to
reviewonly when every touched repo’s code PR is open and ready; the Resume Protocol row and the Stage map box are named (FR-S5, FR-S8). - The capture app’s gate could compare against a stale
forge-et-fe: FR-S5 and FR-S6 fetch it first. - Also:
gh’s flag list decides which words are values;--body=v,-bv,--help/-hhandled; the accepted limit that a PR changing the gate program is judged by that program; the short form quotes the audits it reads; the wave body summary never starts a line withBrowser gate:; AC-H6 names the harness checkout that holds the hook.
Draft 5 — 2026-09-28 (before approval)
Questions the WI-1.3 and WI-1.4 plan authors raised while bringing their plans to Draft 4. Changes:
gh pr create --repo altrium-io/forge-et-harness $FLAGSwas allowed (a false pass:$FLAGScould hold a second--repo, andghtakes the last one): the new FR-H1a refuses an occurrence with a bare expansion, or a flagghdoes not define, before any other check; FR-H1 states the order of the checks.- The last
--draft/-dtoken decides, asghreads it (FR-H2). Theghword is matched ignoring letter case. A command that pipes a file the helper cannot see into a shell is refused when it passed the fast path (FR-H1). --gate-onlyis valid only with--ready(FR-S1). On a branch without the gate program, FR-S2 applies to any non-markdown change.
Draft 6 — 2026-09-28 (before approval)
The Slow lane job was removed from both frontends on main (forge-et-fe#76, forge-et-pwa#30); every check now runs in the one Fast lane, which stops after the static checks on a draft (steps.scope.outputs.full == 'false'). Spec Rev 2 moves FR-11’s description check to the last step of the Fast lane’s full run. In this record, every mention of the Slow lane now means the Fast lane’s full run, and “the Slow lane skips drafts” means “on a draft the Fast lane stops after the static checks”. Nothing else changes: the hook and the skills never depended on the job’s name.
- Also: § Out of scope gains the split-keyword line (
g''h,cr\eate), and FR-H1a names a quoted non-literal word that is not a value flag’s value as unreadable (both raised by WI-1.3’s plan review).
Draft 7 — 2026-09-30 (before approval)
F41 (.forge/specs/F41-tooling-only-dependency-bumps-spec.md, a follow-up of F40) narrows FR-8’s covers rule for dependency-only changes, after forge-et-fe#91 — a Dependabot bump of @types/node, vitest, @vitest/coverage-v8 and lint-staged, none of which the gate runs — failed the Fast lane’s description check. Changes:
- New C-10: a change to only
package.json,pnpm-lock.yamlor both touches no gate input when the lockfile’s gate graph is unchanged; anything C-10 cannot analyse fails closed. - C-1: the lockfile parser is written for the v9 subset and uses only Node built-ins, so
coversandtouches-gate-inputstill run beforepnpm install. - C-2 and C-3: a change C-10 clears is not a gate-input change; when C-10 does not clear it, the reason goes to stderr, and the stdout shapes are unchanged.
- C-7:
dirtyis unchanged; an uncommitted dependency change is stilldirty. - C-9: C-10’s package lists apply the intersection of the versions read, the conservative counterpart of the union rule for the path list.
- Nothing in the hook’s requirements (FR-H*) or the skills’ requirements (FR-S*) changes: both use only the answers of
covers,touches-gate-inputanddirty.
Revision after approval — BUG-044, 2026-10-01
The hook refused any command holding a case statement and the text gh pr create / new / ready, because the tokenizer read a pattern’s closing ) as an unmatched parenthesis (.forge/bugs.md BUG-044). The lead decided the fix on 2026-09-30: teach the tokenizer case, and keep refusing whatever it cannot parse. Rejected: allowing an unparseable command in which no gh word stands in command position. Changes:
- FR-H1, Tokenising, Bash: the
case WORD in … esacgrammar, the reach rule for acdorGH_REPOin an arm, and the case forms that stay unparseable.;;,;∧;&outside a case are now unparseable (before, they were read as;). - From the adversarial review of the change (each a form bash runs that the first version read wrongly, so
ghran inforge-et-fewhile the hook allowed it as a harness PR): reserved words are recognised by their unquoted value, not their source text, soca\⏎seandes\⏎acare read as bash reads them, and a quoted reserved word is a command name ("then" cd xchanges no directory);time -p case …is read as a case, andcoprocis refused; a(after a word is refused outside the forms bash accepts; a shell that reads inherited standard input is refused wherever it stands (FR-H1, the standard-input bullet); afteresac,then,do,done,fi,elseandelifare accepted as bash accepts them; a#that starts a word in a case pattern list is refused, as bash rejects it. An arithmetic command((…))in command position and the header of afor ((…))are read as one unit up to their)), as$((…))and$[…]are, so a(or;;inside them is arithmetic and a<<inside them opens no here-document.
Revision after approval — BUG-098, 2026-10-08
The tokenizer read each part of an if, while, until, for or select statement (if true, then cd x, fi) as a command of its own, so a |, & or redirection after fi or done was recorded on that last word’s command and a cd or GH_REPO in the statement was counted as running in the shell that runs gh (.forge/bugs.md BUG-098). Changes:
- FR-H1, Tokenising, Bash: each such statement is read as one group, as
case … esacis (BUG-044); the forms that stay unparseable are listed there. - FR-H1, Tokenising, Bash: a group or statement after a
!ortimeprefix takes the prefix’s separator, soecho x | time { cd y; }runs thecdin a pipeline element. - FR-H4: a same-shell bash construct that is a pipeline element or a background job runs apart, which the reach rule already applied to
{ …; }groups.