source: .forge/design/harness/docker-resource-labels.md · generated — edit the markdown, not this file

Docker resources: one label and one naming pattern, so cleanup can find them — Design

Status: approved (Draft 3) Author: Tharinda Rajapaksha Reviewed by: two fresh-context review passes, 2026-10-04 (Draft 1 “Needs a redraft”; Draft 2 “Ready after Importants”; Draft 3 applies pass 2’s findings — see ## Revisions). Approval: Tharinda Rajapaksha (lead), 2026-10-04 Date: 2026-10-04 · approved 2026-10-04 Scope: the delivery harness and forge-et-be.

  • Harness: a new PreToolUse hook under .claude/hooks/ (a bash wrapper and a node helper); a shared shell-parsing module, .claude/hooks/lib/shell-parse.mjs, moved out of guard-browser-gate.mjs; the new hook’s fixture test and its README.md row; its registration in .claude/settings.json; .claude/lib/cleanup.sh and .claude/commands/et-cleanup.md; .forge/test-strategy.md (its -p f5-f-baseline example).
  • forge-et-be: README.md (§ Running an isolated stack for a verify run, and § If Postgres refuses to start: the bind-mount ownership case), the header comment of compose.verify.yaml, CLAUDE.md § Common commands, and docs/proofs/pricing/run.sh.

No CI workflow changes. forge-et-fe, forge-et-pwa and forge-et-iaac change nothing: the frontends only point at the backend’s docker compose up -d, and git -C forge-et-iaac grep -iE 'docker (run|compose|build|volume|network)' origin/dev found nothing on 2026-10-04. .claude/CLAUDE.md § Hooks needs no change, because the new hook fails open on a missing dependency like the others. Nothing here is cloud-gated, so .forge/cloud-gated-validation.md gains no row.

Context

Several sessions work in this workspace at once, and most of them start Docker containers: the backend’s own Postgres and LocalStack stack, isolated stacks for verify runs, Testcontainers during the test suite, and throwaway databases for a measurement or a smoke test. /et-cleanup removes what finished ET work left behind; .claude/lib/cleanup.sh’s header lists its rules. Docker is shared with every other project on the machine, so the script removes only what it can tie to ET work. What it can tie today:

  • Compose stacks. Docker Compose labels every container, volume and network it creates with the project name and the project’s folder (com.docker.compose.project, com.docker.compose.project.working_dir). The script reads the folder label: a stopped stack whose folder is gone, or whose folder’s work is merged, is removed; a stack started in a primary checkout is kept as the repo’s own, whatever its project name.
  • Testcontainers containers. Testcontainers labels its own containers (org.testcontainers=true) and removes them after a run; the script removes any left stopped.
  • Images, by name only: an untagged image, or one an ET repo once named and no longer does.
  • Anonymous volumes no container uses, after an hour.

What it cannot tie: containers started with plain docker run. They carry no label, so the script skips them without a word: never removed, never reported. No rule asks for a label today. Recent plans started such containers for throwaway databases — f5f-wi22-pg (.forge/plans/F5-f/F5-f-WI-2.2-plan.md, the NFR-1 timing receipt) and f11a-wi12-pg (.forge/plans/F11-a/F11-a-WI-1.2-plan.md). Both runs removed their containers at the end (docker rm -f …), so the leak happens when a run fails or is interrupted before its teardown. rm -f without -v also leaves the container’s anonymous volume, which the anonymous-volume rule removes an hour later. forge-et-be already has the tool those runs needed, compose.verify.yaml, an isolated compose stack on its own ports.

The names are improvised too. Compose project names in use include f5k3b (.forge/specs/F5-k-access-model-realignment-findings.md), f5-f-baseline (.forge/test-strategy.md, forge-et-be README.md) and et-local-named (forge-et-be README.md, § If Postgres refuses to start: the bind-mount ownership case). A name does not say that it belongs to ET or to which ticket.

Two gaps in the current compose rule. A throwaway verify stack started from a primary checkout (the baseline run on main uses -p f5-f-baseline there) is treated as the repo’s own stack and never removed. And a fresh worktree cut from main with no commits yet counts as “merged”, so its stopped stack can be removed while the worktree is still in use.

A hazard: docker compose up in a linked worktree without -p. With no project name, Compose names the project after the project folder, and every forge-et-be checkout’s folder is called forge-et-be. A worktree’s docker compose up therefore addresses the same project as the primary checkout’s running stack, and Compose recreates containers whose configuration differs — here the bind-mount paths, which compose.yaml writes relative to the project folder. The expected result is that the primary checkout’s stack is replaced by one pointing at the worktree’s empty .local/ folders. AC-7 checks this on a scratch project before the hook relies on it.

Terms

  • Workspace: the parent of the harness’s git common directory — the folder that holds every ET repo (.claude/rules/worktrees-and-waves.md § Worktree Commands, $WS).
  • Primary checkout: <workspace>/<repo> for an ET repo name, and every folder under it except <workspace>/<repo>/.claude/worktrees/…. This matches is_primary in cleanup.sh at the checkout’s root.
  • Linked worktree: a folder at or under a worktree root that git -C <workspace>/<repo> worktree list --porcelain lists for an ET repo, other than the primary checkout itself.
  • Checkout root: the root folder of a primary checkout or of a linked worktree.
  • Not a checkout: any other folder inside the workspace (a scratch folder, a leftover under worktrees/).

Decisions

# Decision Why
D-1 One label marks a resource as ET’s: et.workdir=<checkout root the work belongs to>. It goes on every container, named volume and network ET work creates outside Compose and Testcontainers. The value names the work’s checkout root, never the harness: most sessions run with the harness as their working directory, so a bare $PWD would name the wrong folder. The hook resolves the value (D-5), so a session can write "$PWD" after a cd into the worktree, or a path built from a variable set earlier in the same command; a plan records the command with <wt> in place of the machine path. The script already decides a compose stack’s fate from its folder. One label with the same meaning lets one rule cover everything else.
D-2 One naming pattern: et-<ticket>-<role>, all lower case, a work-item id’s dot written as a dash: et-f5-f-wi2-2-pg, et-f5-f-baseline. It applies to container names, named volumes and networks, and compose project names. Two kinds of compose project are long-lived: a repo’s default project in its primary checkout (forge-et-be), and a project named et-local-<role> started from a primary checkout (a person’s own extra stack, such as et-local-named). Both are kept while their folder exists. People read names; the script reads the label and the project name. Compose project names allow only lower-case letters, digits, dashes and underscores, so one form avoids dots everywhere. et-local- reserves a name for a long-lived stack, so the throwaway rule (D-7) does not delete its data.
D-3 A throwaway database or LocalStack uses the isolated compose stack: docker compose -p et-<ticket>-<role> -f compose.yaml -f compose.verify.yaml up -d --wait, removed afterwards with down -v. A plain docker run stays allowed when it follows D-1 and D-2, or when it is a short foreground command with --rm (D-4 a). Compose labels everything it creates and starts the same images and settings as the developer’s stack.
D-4 A hook enforces D-1 to D-3 in sessions: .claude/hooks/guard-docker-resources.sh, PreToolUse on Bash|PowerShell. It refuses (exit 2):
(a) docker run or docker create (also docker container run/create) unless it has an et.workdir label that resolves to a checkout root (D-5) and a --name starting with et-. A docker run --rm before the image, without -d/--detach, is exempt when every volume it mounts is anonymous or a bind mount. A named volume in -v name:… or --mount source=name must start with et-. Finding the image needs a table of the docker run/create flags that take a value; on a flag not in the table the hook allows the command and warns;
(b) docker volume create or docker network create without an et.workdir label that resolves to a checkout root, or with a name not starting with et-;
© docker compose / docker-compose up, run or create whose project name (-p, --project-name, a COMPOSE_PROJECT_NAME= prefix in bash, $env:COMPOSE_PROJECT_NAME = … earlier in a PowerShell command) does not start with et-, or starts with et-local- while the project folder is not a primary checkout;
(d) the same compose commands with no project name when the project folder is a linked worktree, or cannot be read literally. The project folder is found as Compose finds it: --project-directory; else the folder of the first -f file, or of the first file in a COMPOSE_FILE= prefix (files separated by :, or ; on Windows); else, from the command’s folder (the last literal cd, Set-Location or Push-Location, else the hook input’s cwd), the first folder going upwards that holds a compose.yaml, compose.yml, docker-compose.yaml or docker-compose.yml.
Which commands are checked: for (a) and (b), when the label’s resolved path is inside the workspace, or, with no label, when the command’s folder is; for © and (d), when the project folder is inside the workspace. The message names the rule, the fix (with the resolved path where there is one), and this design.
No rule asked for a label until now; a hook makes the new one hold without anyone remembering it, as the harness does for its other rules (.claude/hooks/README.md § Why Hooks Exist). (d) stops the worktree hazard in § Context before it happens. A foreground --rm command removes itself and its anonymous volumes; a detached one can run forever, so it needs the label. Restricting et-local- to primary checkouts stops it from becoming a way round cleanup.
D-5 The hook reads commands with a shared parser, .claude/hooks/lib/shell-parse.mjs, moved out of guard-browser-gate.mjs: the tokeniser (which understands quotes, heredocs, line continuations, $(…) and PowerShell, so text inside a commit message, a PR body or a heredoc is not mistaken for a command), the command-start reader, and the folder reader, made independent of gh. The browser-gate hook imports it, and its fixture tests are the regression check. Resolving et.workdir: a literal absolute path (Windows forms C:\…, C:/… and /c/… accepted), "$PWD" or $(pwd) resolved from the command’s folder as in (d), or a path built from a variable assigned a literal value earlier in the same command. The resolved path must be a checkout root inside the workspace and not in the harness repo (its primary checkout or any of its worktrees); otherwise the command is refused, and a value the hook cannot resolve is refused too. The hook fails open, with a warning: when jq or node is missing, or the command cannot be tokenised. Accepted gaps (stated in the hook’s header and README row): Docker commands inside a script the command runs (bash run.sh); xargs and aliases; sudo with options (sudo -u x docker …); a COMPOSE_PROJECT_NAME or COMPOSE_FILE exported earlier in the shell or set in a .env file; sessions started inside an app repo, which has no .claude/ of its own. A noisy gate gets disabled (block-dangerous-bash.sh’s contract), and a line-based splitter would refuse this design’s own PR description. One parser for both hooks avoids a second, weaker one. The Bash tool keeps no shell variables between calls, so a variable is only known when the same command sets it. Failing open suits a hygiene rule; the browser gate fails closed because it is a quality gate.
D-6 The script compares paths in one normalised form: a drive letter and \ written as C:/…, and on Windows compared without regard to case. This applies to the new label and to the existing compose folder check. On Windows, $PWD gives /c/Users/… in Git Bash and C:\Users\… in PowerShell, while the script’s workspace path is C:/Users/…; without this, every Windows resource counts as outside the workspace and is kept forever.
D-7 One folder rule for Docker work, labelled containers and compose stacks alike, using the § Terms classes. A stopped container or stack, stopped for at least --min-idle-minutes, is removed (docker rm -v, with a stack’s volumes and networks) when its folder is gone (a worktree this run removed counts as gone), or when its folder is in a primary checkout and it is not long-lived (D-2; a labelled plain container is never long-lived). It is kept while its folder is in an existing linked worktree, whatever the merge state. A labelled volume or network no container uses, older than --min-idle-minutes, follows the same rule. Reported, never removed: a folder that is not a checkout, or outside the workspace; a running labelled container or et-* stack whose folder is gone; and a running labelled container or non-long-lived stack in a primary checkout that has run for more than a day (review docker-container / review docker-stack). The worktree rules already decide when a worktree’s work is finished (merged, idle, nothing uncommitted); the Docker rule follows that decision instead of repeating a weaker merge check. A primary checkout’s throwaway stack had no rule that removed it. A detached database left behind is usually still running, so it has to be reported to be seen.
D-8 A stopped, unlabelled plain container whose image an ET repo names, or once named, is reported as review docker-container, never removed. It is reported on every run until a person removes it. Running unlabelled containers are not reported. It is probably ours, but without the label the script cannot know whose it is. Limiting the report to stopped containers keeps other projects’ running databases on the same machine out of it.
D-9 Images and the build cache are left as they are. A local docker build -t forge-et-be . keeps one tag that each build replaces; the replaced image becomes untagged, which the script already removes. The build cache cannot be attributed to a project in a practical way, so the script keeps pruning what has not been used for 24 hours. A label on images would add a rule and a hook case for no extra cleanup.
D-10 Testcontainers is unchanged. It labels its own containers and removes them after a run; SharedPostgresSpec needs no change.

Requirements

The harness

  • H-1. .claude/hooks/guard-docker-resources.sh (bash wrapper) and guard-docker-resources.mjs (node helper), as D-4 and D-5 say. The wrapper’s fast path: a command that does not contain docker exits 0 before node starts. Folders are classified as § Terms says. The refusal message has the browser-gate hook’s shape: Blocked by Forge harness: …, Reason: …, Fix: …. The header comment states the rules, the exit codes and the accepted gaps.
  • H-2. .claude/hooks/lib/shell-parse.mjs: move the tokeniser (tokenize and the parsers it uses, flatten, reach), the command-start reader (commandStart, literalPrefix) and the folder reader (dirChange, and a computeDir that takes a command’s position in the parsed tree instead of a gh occurrence) out of guard-browser-gate.mjs, which imports them. No change to the browser gate’s behaviour: its fixture tests (.claude/hooks/tests/guard-browser-gate.test.sh and .test.mjs) pass unchanged.
  • H-3. Registration in .claude/settings.json, PreToolUse, matcher Bash|PowerShell.
  • H-4. A fixture test, .claude/hooks/tests/guard-docker-resources.test.sh, one case per AC-1 to AC-5 line, run from anywhere, exit 0 when all pass. It feeds hook input JSON to the hook and never starts a container; folder cases use a temporary workspace with real git repositories and a linked worktree.
  • H-5. .claude/hooks/README.md: a row in § What’s Installed, with the accepted gaps, and the hook’s dependencies (jq, node, git) in § Dependencies.
  • H-6. .claude/lib/cleanup.sh: D-6, D-7 and D-8, with folders classified as § Terms says; the image-name lookup is shared between the image rule and D-8, not copied. The header comment’s Docker list states the new rules. A test option, --test-workspace <dir>: use <dir> as the workspace, skip the git and worktree steps, act only on Docker resources whose folder is under <dir>, and skip the rules that have no folder (Testcontainers containers, anonymous volumes, images, the build cache). The closing summary gets a count line for review docker-container.
  • H-7. .claude/commands/et-cleanup.md: the Docker list states D-7 and D-8, and step 6 says how to handle a review docker-container line: name the container, its image and how long it has been stopped or running, and leave it for the user.
  • H-8. .forge/test-strategy.md: the orchestrator’s verify-stack example becomes -p et-f5-f-baseline.

forge-et-be

  • R-1. README.md § Running an isolated stack for a verify run: project names follow D-2 (-p et-f5-f-baseline); one sentence says a linked worktree always passes -p, with the reason from § Context; one sentence states D-1 for a plain docker run. The et-local-named examples in § If Postgres refuses to start: the bind-mount ownership case keep their name, which D-2 reserves for a person’s long-lived stack.
  • R-2. compose.verify.yaml: the header comment’s example name becomes -p et-f5-f-baseline.
  • R-3. CLAUDE.md § Common commands: the isolated-stack line names the pattern (-p et-<ticket>-<role>), and one line states D-1 to D-3 for a plain docker run, pointing at this design.
  • R-4. docs/proofs/pricing/run.sh: its docker run gains --label et.workdir="$(git -C "$HERE" rev-parse --show-toplevel)", and its cleanup becomes docker rm -fv, so its anonymous volume goes with it. Its default name, et-pricing-proof, already follows D-2.

Acceptance criteria

<wt> below is a linked worktree root in the test’s temporary workspace, <primary> a primary checkout root, and <harness> the harness’s primary checkout.

  • AC-1 (hook, containers). Refused: docker run -d postgres:18-alpine with the hook input’s cwd inside the workspace; docker run -d --name f5f-pg --label et.workdir=<wt> postgres:18-alpine (name); docker run -d --name et-f5-f-pg postgres:18-alpine (label); docker run -d --name et-f5-f-pg --label et.workdir="$PWD" postgres:18-alpine with cwd <harness>; et.workdir=<wt>/src (not a checkout root); et.workdir="$X" with X never assigned in the command; docker run --rm -d --name et-x postgres:18-alpine (detached, no label); docker run --rm -v scratch:/x alpine true (named volume); docker run alpine --rm true (--rm after the image is the container’s argument); sudo docker run -d postgres:18-alpine; CID=$(docker run -d postgres:18-alpine); docker container create --name et-x busybox. Allowed: docker run --rm alpine echo ok; docker run -d --name et-f5-f-pg --label et.workdir=<wt> postgres:18-alpine and the --name=, --label=et.workdir=… and -l et.workdir=… spellings; cd <wt> && docker run -d --name et-f5-f-pg --label et.workdir="$PWD" postgres:18-alpine; WT=<wt>; docker run -d --name et-f5-f-pg --label et.workdir="$WT" postgres:18-alpine; docker run --rm -v et-f5-f-data:/x alpine true; docker ps, docker exec et-f5-f-pg psql …, docker rm -f et-f5-f-pg; docker run -d postgres:18-alpine with cwd outside the workspace; a docker run with a flag not in the table (allowed, with a warning).
  • AC-2 (hook, volumes and networks). Refused: docker volume create scratch; docker volume create --label et.workdir=<wt> scratch. Allowed: docker volume create --label et.workdir=<wt> et-f5-f-data; the same for docker network create.
  • AC-3 (hook, compose). Refused: docker compose -p f5-f-baseline -f compose.yaml -f compose.verify.yaml up -d; --project-name=f5k3b; COMPOSE_PROJECT_NAME=f5k3b docker compose up -d; in PowerShell, $env:COMPOSE_PROJECT_NAME = 'f5k3b'; docker compose up -d; cd <wt> && docker compose up -d; cd <wt>/src && docker compose up -d (the upward search finds <wt>/compose.yaml); docker compose up -d with cwd <wt>; docker compose -f <wt>/compose.yaml up -d run from <primary>; COMPOSE_FILE=<wt>/compose.yaml:<wt>/compose.verify.yaml docker compose up -d; cd "$WT" && docker compose up -d with WT never assigned; cd <wt> && docker compose -p et-local-x up -d. Allowed: the refused project-name cases with -p et-f5-f-baseline; cd <primary> && docker compose -p et-local-named up -d; docker compose up -d in <primary> and in <primary>/src; docker compose -f <primary>/compose.yaml up -d run from a linked worktree of another repo; docker compose down, ps, logs anywhere; any compose command whose project folder is outside the workspace.
  • AC-4 (hook, text that is not a command). Allowed: git commit -m "…; docker run -d x"; gh pr create --body "$(cat <<'EOF' with a body containing docker run -d postgres EOF )"; a docker run \ command continued on the next line with --label … and --name … there.
  • AC-5 (hook, other). A command without docker takes the fast path (the test proves node did not start). With jq or node missing from PATH, the hook exits 0 and warns. A command the tokeniser cannot read exits 0 and warns.
  • AC-6 (cleanup). Run with --test-workspace <tmp> and a short --min-idle-minutes against a temporary workspace holding a git repository named forge-et-be with one linked worktree, on scratch resources created for the test and removed afterwards. Each case is shown by a dry run, then --apply: a stopped labelled container whose folder is gone is removed with its anonymous volume; one whose folder is the linked worktree is kept; one whose folder is the primary checkout is removed; a running one whose folder is gone is kept and reported; an et-* compose stack started from the primary checkout is removed once stopped, and an et-local-* one there is kept; a labelled unused volume follows the same rules; a folder that is not a checkout is reported. No action line names a resource outside <tmp>, a Testcontainers container, an anonymous volume, an image or the build cache. Separately, a dry run with no options shows a stopped unlabelled postgres:18-alpine scratch container as review docker-container.
  • AC-7 (the worktree hazard). Before the hook ships, the § Context claim is checked on a scratch compose file in two temporary folders with the same name, never on a real stack: up -d in the second folder recreates the first folder’s container. If it does not, D-4 (d) and R-1’s sentence are dropped and this design is revised.
  • AC-8 (Windows). A Windows developer runs AC-1’s cd <wt> && … "$PWD" case and AC-6’s first case once in Git Bash and once in PowerShell, and the script removes the container (D-6). If no Windows run is possible before the harness PR merges, D-6 is recorded as unverified on Windows in .forge/owed.md with the developer named.
  • AC-9 (the backend). bash docs/proofs/pricing/run.sh still passes, and docker inspect of its container while it runs shows the label with the checkout’s root. The README and CLAUDE.md examples run as written against compose.verify.yaml.
  • AC-10 (the browser gate). After H-2, bash .claude/hooks/tests/guard-browser-gate.test.sh and node --test .claude/hooks/tests/guard-browser-gate.test.mjs pass with no change to either test file.

Scope

In scope: containers, named volumes, networks and compose projects that a session creates for ET work, and the cleanup script’s handling of them and of compose stacks.

Out of scope, each for a stated reason:

  • Commands a person types in their own terminal. Hooks run only in Claude Code sessions. The convention still applies to people through R-1 and R-3, and D-8 reports what a person left unlabelled and stopped.
  • Images and the build cache (D-9). Testcontainers (D-10).
  • Docker commands inside scripts a session runs, and the other accepted gaps in D-5. The one such script in the repos is fixed by R-4.
  • Existing records. Plans and findings that name old containers are point-in-time records and are not rewritten.

Rollout

  1. The forge-et-be PR: R-1 to R-4, with AC-9’s output, a build record and a review record (.claude/rules/review-record.md). It is harmless without the hook, so it merges first.
  2. The harness PR, after this design is approved and step 1 has merged: H-1 to H-8 and this record, with AC-1 to AC-7 and AC-10 run and their output in the PR description. One chore: PR.
  3. AC-8 on Windows, by a Windows developer, as soon as one is available.
  4. The next /et-cleanup reports any stopped unlabelled container left from before (D-8); a person removes or keeps each one.

Rejected alternatives

Alternative Why rejected
Only a written convention, no hook A convention has to be remembered by whoever writes the next plan step, and a miss stays invisible until someone reads a cleanup report.
Recognising ET containers by name pattern alone (et-*) A name cannot say which folder the work belongs to, so the script could not apply the folder rule; it would have to remove on age alone, which is unsafe while another session uses the container.
An unresolved et.workdir="$PWD" Most sessions run from the harness, so $PWD names the harness’s primary checkout and the container would be removed an hour after it stops, whatever the state of the work. The hook resolves it instead (D-5).
A label value that must always be a literal path Sessions build paths from $WS/$WT (worktrees-and-waves.md § Worktree Commands), and plans would carry machine paths.
A second, line-based shell parser in the new hook It refuses text inside commit messages, PR bodies and heredocs; the browser-gate parser already reads them correctly, in bash and PowerShell.
A --only-workdir filter on the real workspace for testing A primary checkout must be <workspace>/<repo>, so a temporary folder cannot stand in for one, and the rules with no folder would still act on other sessions’ resources.
Labelling Testcontainers containers too Testcontainers already labels and removes its own.
A label on locally built images Each build replaces the one tag and the script already removes the untagged result (D-9).
Blocking every docker run and requiring Compose A short foreground docker run --rm … leaves nothing behind.

Where each rule lives

Rule Home
The label, the naming pattern and “use the isolated compose stack” forge-et-be CLAUDE.md § Common commands and README.md § Running an isolated stack for a verify run; the hook’s refusal message
The orchestrator’s verify-stack name .forge/test-strategy.md
Enforcement in sessions, and its accepted gaps .claude/hooks/guard-docker-resources.sh header; .claude/hooks/README.md row; registered in .claude/settings.json
The shell parser both hooks use .claude/hooks/lib/shell-parse.mjs
What the cleanup removes and reports .claude/lib/cleanup.sh header; .claude/commands/et-cleanup.md
Why this design

The rule is not added to .forge/design/coding-standards.md: that document is condensed into every app repo’s CLAUDE.md, and only forge-et-be creates Docker resources.

Open questions

  • Q-1 [lead]. Should the rule also cover a person’s own terminal, through a git hook or a shell function? This design says no: sessions start almost all of these containers, and D-8 reports what a person leaves stopped and unlabelled. Decided 2026-10-04 (lead): no, as this design says.
  • Q-2 [lead]. D-7 removes a stopped throwaway stack or labelled container started from a primary checkout after --min-idle-minutes (one hour by default). A person who stops one there to resume it later loses it and its data. The way to keep one is a stack named et-local-<role>. Acceptable? Decided 2026-10-04 (lead): acceptable, as D-7 says.

Revisions

Rev 3 — 2026-10-26 (rename)

  • The command /et-repo-cleanup is now /et-cleanup and its script .claude/lib/repo-cleanup.sh is now .claude/lib/cleanup.sh, because it cleans Docker as well as repositories. Every pointer in this design uses the new names; the rules are unchanged.

Rev 2 — 2026-10-05 (BUG-062)

  • D-5, accepted gaps: timeout and sudo with options (sudo -u x docker …) are no longer gaps. The shared commandStart now reads each prefix command with its own options and operands (BUG-062, forge-et-harness#459), so timeout 60 docker run …, sudo -u root docker run … and nice -n 5 docker run … are checked; guard-docker-resources.test.sh covers them. xargs and aliases stay gaps. D-5’s text above is kept as approved.

Rev 1 — 2026-10-04 (implementation clarifications)

  • H-2, the shared parser: .claude/hooks/lib/shell-parse.mjs re-exports the parser from guard-browser-gate.mjs instead of holding a moved copy. Moving about 1,400 lines would have meant retyping them through the Edit and Write tools (the only way harness files under .claude/ are changed, .claude/CLAUDE.md § Boundaries), with a real risk of copying errors in regex-heavy code; the re-export gives the same import path, so a later physical move changes only those two files. guard-browser-gate.mjs now exports literalPrefix, splitWord, baseName, commandStart, dirChange and envChdir, and its folder reader is split into a gh-independent dirBefore(target, ctx), which computeDir calls before applying env -C and Start-Process -WorkingDirectory. The browser gate’s behaviour is unchanged (AC-10); one message now says “joined to the command by &&” where it said “joined to gh by &&”, and no test asserts that text.
  • H-3: the hook is registered with a 15-second timeout, beside the browser gate under the Bash|PowerShell matcher.
  • H-6: a container that never ran has year 0001 as its finish time, so the script measures it from its creation time instead.
  • From the implementation review (fresh-context, 2026-10-04):
    • Scope first: a docker run outside the workspace is not checked at all, named volumes included.
    • Absolute labels: the label must resolve to an absolute path with no . or .. segment, because Docker stores the text as the shell passes it and the cleanup compares that text.
    • Create commands: volume create and network create read flags after the name.
    • Detached runs: a trailing & counts as detached for the --rm exemption.
    • Names: a name passes when its text as the shell sees it starts with et-, so "et-f5-f-$ROLE" passes and $NAME alone does not.
    • Compose flags: compose reads -p<value>, -f<value> and the --workdir alias of --project-directory.
    • Case: the fast path ignores case.
    • Accepted gap: timeout is added to the accepted gaps.
    • Dry runs: in the cleanup script, a worktree that a dry run would remove counts as gone, so the dry run shows the Docker removals that --apply makes.
    • Paused containers: they count as running.
    • Unused et-* volumes: one with no label (which docker run -v et-…:/x creates) is reported as review docker-volume.
    • Labels outside the workspace: a label naming a folder outside the workspace gets a keep line, not a review line: it is not ET’s work.
  • AC-7 result: on a scratch project in two folders named etacseven, up -d in the second folder recreated the first folder’s container with its bind mount pointing at the second folder (Container etacseven-one-1 Recreated). D-4 (d) stands.

Draft 3 — 2026-10-04 (before approval)

Applies the second review pass (verdict “Ready after Importants”):

  • Folder classes (A, H): § Terms defines primary checkout, linked worktree, checkout root and “not a checkout”; a subfolder of a primary checkout is the primary checkout; D-4 (d) follows Compose’s upward search for the compose file and its COMPOSE_FILE separators; the label must name a checkout root.
  • Which commands are checked (B): for (a) and (b), by the label’s path, or by the command’s folder when there is no label, so an unlabelled docker run in the workspace is refused.
  • Testing the script (C, D): --docker-only and --only-workdir replaced by --test-workspace <dir>, which uses a temporary workspace and skips the rules with no folder.
  • Running containers in a primary checkout (E): reported after a day.
  • The label’s value (F): the hook resolves "$PWD", $(pwd) and variables assigned in the same command; plans record <wt>.
  • The parser (G): H-2 moves the tokeniser, the command-start reader and a gh-independent folder reader into .claude/hooks/lib/shell-parse.mjs; AC-10 checks the browser gate is unchanged.
  • Nits (I, J, K): et-local- only from a primary checkout and kept while its folder exists; a flag table for finding the image, failing open on an unknown flag; the image-rule citation points at the script header; sudo with options listed as an accepted gap.

Draft 2 — 2026-10-04 (before approval)

Applied the first review pass (verdict “Needs a redraft”): the browser-gate tokeniser instead of line splitting, with PowerShell covered and the accepted gaps listed; Compose’s project-folder order; a label value naming the work’s checkout, never the harness; --rm exempt only in the foreground with no named volume; one folder rule for labelled containers and compose stacks that keeps anything in an existing linked worktree, removes throwaway stacks from a primary checkout, keeps et-local-* stacks and reports running containers whose folder is gone; D-8 limited to stopped containers; Windows path normalisation (D-6, AC-8); test options for the script; .forge/test-strategy.md added and the coding-standards.md requirement dropped; review docker-container handling in the command; § Context corrected (no rule existed, and the cited runs removed their own containers); the backend PR merges first.

Generated from .forge/design/harness/docker-resource-labels.md by .claude/lib/render-docs-html.js. Markdown is canonical.